Networking¶

Networking apps manage communication internal to the instrument. (They are distinct from utilities in that they run until killed.)

sshDigger¶

sshDigger uses the autossh utility to form a robust SSH tunnel or port forward to a remote host. In addition, the forked autossh process is monitored, and if it dies a new one is created.

The base configuration is normally located at /opt/MagAOX/config/sshTunnels.conf (view in magao-x/config). It should contain options applicable to all tunnels, as well as the tunnel definitions themselves.

The tunnel name must be specified with the -n command line option. The tunnel_name denotes the section in the configuration file(s) which contains the specification of the tunnel. sshDigger is normally configured via a base configuration file, hence all other command-line arguments are optional.

This app does not require that an instance of specific configuration tunnel_name.conf be available. If one is available matching the name given with the -n tunnel_name option, then any settings contained therein will override those given in the base config file.

Tunnel Specification¶

Tunnels are specified by a section in the configuration files, normally the base sshTunnels.conf file. The section must have the following members

[tunnel_name]
remoteHost=resolvable_name
localPort=X
remotePort=Y
compression=true-or-false

Where - resolvable_name is an ip address or host name. This can include a user name user@ at the beginning if needed. - X denotes the integer local port number. - Y denotes the integer remote port number - true-or-false should be either true or false, and specifies whether this tunnel will use compression, see below.

This results in ssh being started with

$ ssh -nNTL X:localhost:Y resolvable_name

by the autossh utility.

For example, to create an SSH tunnel for magaox_aoc_to_rtc_indi:

$ /opt/MagAOX/bin/sshDigger -n magaox_aoc_to_rtc_indi

Which expects a configuration entry of the form:

[magaox_aoc_to_rtc_indi]
remoteHost=rtc
localPort=7630
remotePort=7624

This then securely forwards traffic from localhost:7630 to the INDI server on rtc:7624.

Compression¶

The INDI protocol uses XML, and can therefore be a heavy user of bandwidth. Tunnels for INDI should normally be compressed for remote connections, and may be compressed depending on performance for instrument LAN tunnels.

Tunnels for milkzmq image transfer should NOT be compressed. The images are already compressed if possible, and the algorithm used by ssh will not provide significant compression of this type of data. This would just consume CPU resources without benefit.

xindiserver¶

xindiserver wraps the standard indiserver program in a MagAO-X interface. This includes exposing configuration options, and capturing logs which are reformatted in the flatlogs binary logging system.

Options¶

Sh ort	Long	Config-File *	Type	De scr ipt ion
`- m`		indiserver.m	int	i ndi ser ver ki lls cli ent if it g ets m ore t han t his m any MB b ehi nd, d efa ult 50
`- N`		indiserver.N	bool	in dis erv er: ign ore /tm p/n oin di. Ca pit ali zed to av oid co nfl ict w ith ` – nam e`
`- p`		indiserver.p	int	in dis erv er: alt ern ate IP po rt, d efa ult 7 624
`- v`		indiserver.v	int	in dis erv er: log v erb osi ty, -v, -vv or - vvv
`- x`		indiserver.x	bool	e xit af ter l ast cli ent di sco nne cts – FOR PRO FIL ING O NLY
`- L`	`--local`	local.drivers	vector of strings	L ist of lo cal d riv ers to sta rt.
`- R`	`--remote`	remote.drivers	vector of string	L ist of rem ote d riv ers to sta rt, in the f orm of n ame @ho stn ame w ith out the po rt. Ho stn ame ne eds an en try in rem ote .ho sts
`- H`	`--hosts`	remote.hosts	vector of string	L ist of rem ote hos ts, in the f orm of `` hos tna me[ :re mot e_p ort ]:l oca l_p ort . ``r emo te_ por t is op tio nal if it is the I NDI de fau lt.

Driver Specifications¶

Lists of driver names are passed to xindiserver via the configuration system. Drivers can be either local or remote.

Driver names can not be repeated, whether local or remote.

Local Drivers¶

Drivers running on the same machine are specified by their names only. On the command line this would be

--local=driverX,driverY,driverZ

and in the configuration file this would be

[local]
drivers=driverX,driverY,driverZ

Remote Drivers¶

Drivers running a remote machine are specified by their names and the name of the SSH tunnel to that machine. xindiserver parses the sshTunnels.conf config file as part of configuration.

NOTE: the tunnel specification is by the tunnel name (the section in the config file), not the host name.

On the command line this would be

--remote=driverR@tunnel_name_1,driverS@tunnel_name_2,driverT@tunnel_name_1

and in the configuration file this would be

[remote]
drivers=driverR@tunnel_name_1,driverS@tunnel_name_2,driverT@tunnel_name_1

In both cases it must be true that sshTunnels.conf contains a valid tunnel specification for tunnel_name_1 and tunnel_name_2.

Exit Status¶

If there are no errors xindiserver runs until killed.

If the specified port is already in use, i.e. due to a previously running indiserver, then xindiserver will produce a log entry, change to state FAILURE, and exit.

If the indiserver process exits for any reason, then xindiserver will produce a log entry, change to state FAILURE, and exit.

If the xindidriver program for a driver reports that it can not get a lock, which indicates that another instance of xindidriver already has the FIFO open, then xindiserver will produce a log entry, change to state FAILURE, and exit.

Troubleshooting¶

If indiserver exits abnormally (this is extremly rare, and is not expected except due to operator error!), it can leave the xindidriver processes running. A subsequent attempt to restart will fail when new instances of xindidriver can not lock the FIFOs. The solution is manually kill each of the xindidriver processes, which will have the symlinked names of the MagAOXApp they are communicating with. Instructions can be found in the troubleshooting guide.