xpans(1)

✨ NAME ✨

okay so hi bestie 💖 welcome to xpans — literally the XPA Name Server, periodt. that's the whole name. she's the name server. she serves names. iconic behavior honestly 🎀

---

🌸 SYNOPSIS 🌸

xpans [-h] [-e] [-k sec] [-p port] [-l log] [-s security log] [-P n]

---

💅 OPTIONS 💅

• -h — prints a help message, aka the "what do i even do" text. bestie behavior fr.
• -e — exits when there are no more XPA connections. like, she leaves the party when everyone else has left. no lingering. 🦋
• -k — sends keepalive messages every n sec.
• -l — logs data base entries to the specified file.
• -p — listens for connections on the specified port.
• -s — logs security info for each connection to the specified file.
• -P — accepts proxy requests, using P=1 (same thread) or P=2 (separate thread).
• --version — displays the version and dips. 👑

---

👑 DESCRIPTION 👑

so like. the xpans name server is an XPA-enabled program that manages the names and ports of XPA access points. she just. appears. she gets started automatically whenever an XPA access point gets registered. and you can go talk to her using xpaget to get a list of all the registered access points. slay 💖

xpans is genuinely the crucial link between XPA clients and servers, no cap. when an XPA server defines an access point using XPANew(), XPACmdNew(), or XPAInfoNew(), that access point's name gets registered in the name service along with its connection info. then the name server matches the class:name templates that XPA clients hand her against those registered entries, so the clients can actually reach the right servers. it's giving matchmaker. it's giving wingwoman. 💅

---

🌈 the keepalive situation (iykyk)

the socket connection between an XPA-enabled program and xpans stays open until the program exits (or explicitly closes the connection). but — and this is the plot twist — apparently some Internet equipment (hi, DSL modems 💀) can make that connection time out after a period of inactivity. so to stop that from happening, you can use the -k [sec] switch to send a short keep-alive message to every open connection after the specified time delay.

note bestie: this application-level keep-alive is only necessary if you're serving XPA-enabled clients over the Internet and have to deal with long-term connections involving DSL or similar equipment. XPA uses the ordinary socket-level keep-alive, which works for all other cases.

NB (12/2/2009): Out-of-band (URG) TCP 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 XPA server as well. Proceed with caution! 😭

---

✨ how she starts up

xpans will start automatically (assuming she can be found in the user's path) when the first XPA access point is registered. so like, you don't even have to start her yourself. main character energy. but when she is started automatically, the -e switch is used, so the name server will exit when there are no more XPA access points registered. if you want her to keep running continually, just start her manually without the -e switch. 🫶

---

🎀 the -l log (the receipts)

the name server keeps a log of registered access points if the -l [log] switch is used on the command line (and yes, this is the case for automatic start-up). the log has enough name and connection information to let you re-register all XPA access points in case the name server process gets terminated prematurely. for example, after the ds9 access point is registered, the log will contain the entry:

add 838e2f67:1863 ds9 ds9 gs eric

if xpans gets terminated but ds9 is still running, you can re-register both access points for the ds9 process by running:

xpaset -p 838e2f67:1863 -nsconnect

notice that the ip:port specifier is used with xpaset to bypass the need for contacting the name server (which does not have the name registered yet!). sneaky. clever. obsessed. ⭐

---

🔥 the -s security log

the name server keeps 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 xpaget command), information gets logged about the host issuing the command and the parameters passed into the program. this is most useful when xpans is accepting connections from untrusted machines. 👀

---

💜 registering and unregistering

when an XPA access point is removed by a server using XPAFree(), the access information is removed from the name server. and if an XPA-enabled process is terminated, all names registered by that process get removed automatically. the log file is always updated to reflect the currently registered access points. always. she keeps it current fr fr.

---

🦋 the xpans access point

the name server herself has an XPA access point named xpans registered, and through it you can find out information about currently registered access points (assuming you have access to the name server; see XPA Access Control for more information). for each registered access point, this is what comes back:

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

for example, to display all currently registered access points, simply execute:

xpaget xpans

continuing the ds9 example from above, this will return:

DS9 ds9 gs 838e2f67:1863 eric

if the same program has been started with different XPA access names, you can look up only names matching a specified template. for example, assume that ds9 has been started up using:

ds9 &
ds9 -title ds9-1-eric &
ds9 -title ds9-2-eric &

to look up all ds9 access points which end in .eric and which can be accessed using xpaset, use:

xpaget xpans "DS9:*.eric" "s" "*"

this will return:

DS9 ds9-2-eric gs 838e29d3:42102 eric
DS9 ds9-1-eric gs 838e29d3:42105 eric

the third argument "*" 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. filtering queen. 🎀

---

🌸 XPA_METHOD and the socket vibe check

the name server uses the XPA_METHOD environment variable to decide whether she should listen for requests on INET or LOCAL sockets. and since XPA access points also use this environment variable, the choice of socket method stays consistent. note that, when INET sockets are used, a local server can be accessed from remote machines if the XPA_NSINET environment variable is set to point to the local machine. see XPA Environment Variables for more information. ✨

---

💀 the proxy feature (experimental, bestie)

an experimental feature of xpans is her ability to act as a proxy to XPA servers behind firewalls that want to communicate with external processes. the basic idea is this: an XPA server (call it "foo") on host1, possibly behind a firewall, makes a remote connection to a proxy-enabled xpans program on host2 (specifying host2's XPA method). for example:

xpaset -p foo -remote 'host2:28571' + -proxy   # on host1

when this is done, host2 can use xpaset, xpaget, and xpainfo calls to communicate with the XPA 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 XPASet() or XPAGet() call to foo, passing commands and data back and forth between the two programs. it's giving tunnel. it's giving sneaking past the bouncer. 🔥

by default, proxy connections are not allowed by xpans. if the -P switch is specified with a value of 1, proxy connections 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 XPA_IOCALLSXPA environment variable, so that multiple proxy requests can be handled at the same time, instead of serially. 💅

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. 🫶

---

🌈 SEE ALSO 🌈

see xpa(n) for a list of XPA help pages 💖

---

okay that's the whole thing bestie, you're basically an xpans expert now, no cap 👑

version 2.1.15 · July 23, 2013 · that's the SAORD Documentation glow-up, xoxo 💅✨