path: root/xpa/man/man1/xpans.1

.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.13)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "xpans 1"
.TH xpans 1 "July 23, 2013" "version 2.1.15" "SAORD Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
\&\fBxpans: the \s-1XPA\s0 Name Server\fR
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  xpans [\-h] [\-e] [\-k sec] [\-p port] [\-l log] [\-s security log] [\-P n]
.Ve
.SH "OPTIONS"
.IX Header "OPTIONS"
.Vb 8
\&  \-h            print help message
\&  \-e            exit when there are no more XPA connections
\&  \-k            send keepalive messages every n sec
\&  \-l            log data base entries to specified file
\&  \-p            listen for connections on specified port
\&  \-s            log security info for each connection to specified file      
\&  \-P            accept proxy requests (P=1) using separate thread (P=2)
\&  \-\-version     display version and exit
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The xpans name server is an XPA-enabled program that is used to
manage the names and ports of \s-1XPA\s0 access points. It is started
automatically when an \s-1XPA\s0 access point is registered. You can access
the name server using xpaget to get a list of registered access points.
.PP
The \fIxpans\fR name server provides a crucial link between \s-1XPA\s0
clients and servers.  When an \s-1XPA\s0 server defines an access point using
\&\fIXPANew()\fR, \fIXPACmdNew()\fR, or \fIXPAInfoNew()\fR, the name of the access point
is registered in the name service, along with connection information.
The name server then matches class:name templates passed to it by \s-1XPA\s0
clients with these registered entries, so that the clients can
communicate with the appropriate servers.
.PP
The socket connection between an XPA-enabled program and
\&\fIxpans\fR is kept open until the former exits (or explicitly
closes the connection). Apparently, some Internet equipment (e.g. \s-1DSL\s0
modems) can cause such a connection to time-out after a period of
inactivity. To prevent this from happening, you can use the \-k
[sec] switch to send a short keep-alive message to each open
connection after the specified time delay. (Note that this
application level use of keep-alive is necessary only if you are
serving XPA-enabled clients over the Internet and have to deal with
long-term connections involving \s-1DSL\s0 or similar equipment.  \s-1XPA\s0 uses
the ordinary socket-level keep-alive, which works for all other cases.)
\&\s-1NB\s0 (12/2/2009): Out-of-band (\s-1URG\s0) \s-1TCP\s0 data, used by xpans
keep-alive, is changed by some Cisco routers into in-band data.
Encountering such a router will break the keep-alive function and may
break your \s-1XPA\s0 server as well. Proceed with caution!
.PP
The \fIxpans\fR program will be started automatically (assuming it
can be found in the user's path) when the first \s-1XPA\s0 access point is
registered.  It therefore need not be started explicitly.  However,
when started automatically, the \fI\-e\fR switch is used, so that
the name server will exit when there are no more \s-1XPA\s0 access points
registered. If you wish to keep the name server running continually,
simply start it manually without the \fI\-e\fR switch.
.PP
The name server will keep a log of registered access points if the
\&\fI\-l [log]\fR switch is used on the command line (this is the
case for automatic start-up).  The log contains enough name and connection
information to allow you to re-register all \s-1XPA\s0 access points in case
the name server process is terminated prematurely. For example, after
the ds9 access point is registered,the log will contain the entry:
.PP
.Vb 1
\&  add 838e2f67:1863 ds9 ds9 gs eric
.Ve
.PP
If \fIxpans\fR is terminated but ds9 still is running, you
can re-register both access points for the ds9 process by running:
.PP
.Vb 1
\&  xpaset \-p 838e2f67:1863 \-nsconnect
.Ve
.PP
Notice that the ip:port specifier is used with \fIxpaset\fR to bypass
the need for contacting the name server (which does not have the name
registered yet!)
.PP
The name server will keep a log of security information if the \-s
[security log] switch is used on the command line. For each
accepted connection, (including connections via the \fIxpaget\fR
command), information will be logged about the host issuing the
command and the parameters passed into the program. This is most
useful when \fIxpans\fR is accepting connections from untrusted
machines.
.PP
When an \s-1XPA\s0 access point is removed by a server using \fI\fIXPAFree()\fI\fR,
the access information is removed from the name server.  If an
XPA-enabled process is terminated, all names registered by that process
will be removed automatically.  The log file is always updated to
reflect the currently registered access points.
.PP
The name server itself has an \s-1XPA\s0 access point names \fIxpans\fR
registered through which you can find out information about currently
registered access points (assuming you have access to the name server;
see \s-1XPA\s0 Access Control for more information).
For each registered access point, the following information is returned:
.PP
.Vb 5
\&  class         # class of the access point
\&  name          # name of the access point
\&  access        # allowed access (g=xpaget,s=xpaset,i=xpainfo)
\&  id            # socket access method (host:port for inet, file for local/unix)
\&  user          # user name of access point owner
.Ve
.PP
For example, to display all currently registered access points, simply execute:
.PP
.Vb 1
\&  xpaget xpans
.Ve
.PP
Continuing the example of ds9 above, this will return:
.PP
.Vb 1
\&  DS9 ds9 gs 838e2f67:1863 eric
.Ve
.PP
If the same program has been started with different \s-1XPA\s0 access names,
you can look up only names matching a specified template. For example,
assume that ds9 has been started up using:
.PP
.Vb 3
\&  ds9 &
\&  ds9 \-title ds9\-1\-eric &
\&  ds9 \-title ds9\-2\-eric &
.Ve
.PP
To lookup all ds9 access points which end in \*(L".eric\*(R" and which can
be accessed using \fIxpaset\fR, use:
.PP
.Vb 1
\&  xpaget xpans "DS9:*.eric" "s" "*"
.Ve
.PP
This will return:
.PP
.Vb 2
\&  DS9 ds9\-2\-eric gs 838e29d3:42102 eric
\&  DS9 ds9\-1\-eric gs 838e29d3:42105 eric
.Ve
.PP
The third argument \*(L"*\*(R" requests all access points from all users.
You also can specify a specific user name and only access points
registered by that user will be returned.
.PP
The name server uses the \fI\s-1XPA_METHOD\s0\fR environment variable
to determine whether it should listen for requests on \s-1INET\s0 or \s-1LOCAL\s0
sockets.  Since \s-1XPA\s0 access points also use this environment variable,
the choice of socket method will be consistent.  Note that, when \s-1INET\s0
sockets are used, a local server can be accessed from remote machines
if the \fI\s-1XPA_NSINET\s0\fR environment variable is set to point to
the local machine.  See
\&\s-1XPA\s0 Environment Variables
for more information.
.PP
An experimental feature of xpans is its ability to act as a proxy to
\&\s-1XPA\s0 servers behind firewalls that want to communicate with external
processes.  The basic idea is the following: an \s-1XPA\s0 server (call it
\&\*(L"foo\*(R") on host1, possibly behind a firewall, makes a remote connection
to a proxy-enabled xpans program on host2 (specifying host2's \s-1XPA\s0 method).
For example:
.PP
.Vb 1
\&  xpaset \-p foo \-remote \*(Aqhost2:28571\*(Aq + \-proxy   # on host1
.Ve
.PP
When this is done, host2 can use xpaset, xpaget, and xpainfo calls to
communicate with the \s-1XPA\s0 server foo. All command communication is
performed via the xpans socket connection between foo on host1 and
xpans on host2 (which was initiated by foo from inside the firewall).
Data communication is similarly performed using a socket connection
initiated on host1 (usually with a port value two greater than the
port value of the main xpans socket connection). An xpaset or xpaget
call on host2 contacts xpans, which performs an \fIXPASet()\fR or \fIXPAGet()\fR
call to foo, passing commands and data back and forth between the two
programs.
.PP
By default, proxy connections are not allowed by xpans. If the \-P switch is
specified with a value of 1, proxy connection are allowed, but all proxy
communication is performed in the same thread as xpans processing. If
a value of 2 is specified, the proxy processing is performed in a
separate thread (assuming pthreads are supported on your system).
Because xpa callback processing of any type can take a long time and
therefore can interfere with normal xpans processing, threaded proxy
connections (\-P 2) are recommended.  When using proxy connections, it
might also be useful to set the \s-1XPA_IOCALLSXPA\s0 environment variable, so
that multiple proxy requests can be handled at the same time, instead of
serially.
.PP
Note that this proxy interface to xpans is experimental. It is used
to provide remote data analysis capabilities on the Chandra-Ed system
using ds9.  (See http://chandra\-ed.cfa.harvard.edu and
http://hea\-www.harvard.edu/saord/ds9 for more details). As always, please
contact us if you have problems or questions.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
See xpa(n) for a list of \s-1XPA\s0 help pages