From the client side there are two ways to connect:
An environment variable provides the option of a default host (which may be overloaded by directly specifying the host in the filename) and also makes it easy to redirect your entire application to different hosts.
environment variable: DISAMNET=[user@]my.host.com[:port]
or
filename prefix: disam://[[user@]my.host.com[:port]]/path/to/isam/file
Where host can be in 123.4.5.6 notation also, slashes can be forward or backward, and prefix is not case sensitive.
disam:// files override DISAMNET, and DISAMNET overrides local files.
disam:///my/local/file will force local files, when DISAMNET is set.
disam://[URL]//my/root/path will force root access, whereas any single slash paths will be taken as relative to the current working directory of the server process.
DOS paths with drive letters are also acceptable on server platforms that can handle this notation.
user@host creates an executed pipe connection, by default ssh, in place of the default socket connection, and this in turn can be over-ridden by setting DISAMSSH=[/path/to/local/]executable, see details below.
The underlying logic of the disam URL syntax is that the first character must be a slash, in either direction, immediately followed by another in the same direction, followed by a string of any length, followed by one final terminating slash, in the same direction.
DISAMNET=my.lan.server dcheck my_lan_file dcheck DISAM://my.lan.server/my_lan_file DISAMNET=joe@my.remote.host dcheck my_remote_file dcheck DISAM://joe@my.remote.host/my_remote_file
Please Note that disamnet will accept both full and relative paths in filenames, meaning that DISAM://server.lan/my_file points to a file in the current working directory of the server process on server.lan, whereas DISAM://server.lan//tmp/my_file points to a file in the /tmp directory of the server.
DISAMNET is designed to operate over a full duplex pair from the ground up to get the best performance out of local area networks, and also to supply full bandwidth standard in/out communications for easy and/or direct links over a wide range of options.
Connections at the moment are either TCP/IP socket(2) calls to a disamnet server, or pipe(2) handles to an executable proxy - the default is ssh.
On connecting to the given server port number the client opens the first handle for reading, and reads two bytes in machine independant order, to determine the second connection port on which to open the second handle, and to which it writes an endian order check integer (short value 0x1234) to initiate service.
At the moment the next highest port number is used for the second socket, but other strategies are planned for, and will probably be required.
Socket connections require that clients are able to reach both ports on your server, so when making adjustments to firewalls, please remember to configure both ports.
Both handles are opened in the normal dup2(2) manner, and the client then sends the endian order check value directly, to initiate service.
The default pipe call is ssh, unless DISAMSSH is set in the environment,
in which case the call is $DISAMSSH
The default ssh call expects that disamnet will be found in the user path, and also that either ssh(1) authentication has already been sorted out, or your application is otherwise able to handle the user intervention needed to get authenticated.
Please also see isconfig.h
You can change the environment keywords and default port numbers here.
Please Note
ISADMIN 1 in isconfig.h is mandatory - disamnet relies on isadmin ID.
util/disamnet.c includes the same internal module - base/isremote.c - that the disam libary calls internally, and while this has no real advantage at the moment, it is designed to allow the server binary more direct access to the routines it will need in common with the disam library in order to properly handle caching and other anticipated future enhancements.
For this reason disamnet must have base/isremote.c visible in the include path, but is otherwise compiled and linked as for any other disam utility.
service administration is based on the disamnet utility
disamnet -lfdv -P(ort) -I(nterface) opts: l(isten) f(ork) d(aemon) v(erbose)
disamnet with no arguments will read on stdin, and reply on stdout, and as such should be compatible with all connection hosting and forwarding agents that recognise this standard, including disam itself, which adopts the same protocol internally.
option -l will listen for incoming TCP clients.
option -I<address> specifies the interface to listen on, default is all interfaces.
option -P<number> specifies the port, for default see ISNETPORT define.
With option -l alone disamnet will only serve one client at a time, and
all other clients will wait until the port is free - this may be used in
testing, or for deliberate load limiting in, for example, round robin
mitigation strategies, etc.
Option -lf runs a multi-client forking
service, and is usually invoked
as -lfd, to make disamnet run in the background automatically, in which
case it will also set signal(2) SA_NOCLDWAIT and close the terminal file
handles.
Please note that (by default) -f is burst
limited to one new client per
second, and that there are a finite number of slots in which to stack the
incoming connections, pending accept. This may be adjusted or disabled via
the BURST defines at the top of util/disamnet.c
Please note that lowercase options are non-standard in that they must all be given at once, as in -lfd, and will not be recognised individually.
Please note that uppercase options expect a value without a following space, as in -I127.0.0.1, and will not work otherwise.
disamnet with listening option(s) and no further arguments will run as a disam service, after first checking the endian token read from the client.
disamnet may also be called with a command line following - taken as the first word not starting with a dash - in which case it will operate as a general pipe service that will listen for and connect clients to whatever executable process is specified on the remaining command line.
examples:
disamnet -lfd -P12300 -I127.0.0.1
This runs a complete multi-client service, which listens on ports 12300
and 12301, and is bound to the machine loopback
interface only, and as
such will only respond to calls from clients on the same machine.
disamnet -l /home/joe/my_debug_shell
This listens for a single client on the default port on all interfaces, and calls the given file, which must be executable, and either given as a fully qualified path, or found in server PATH environment.
/home/joe/my_debug_shell:
#!/bin/sh # run test disamnet service with debugs turned on ISDEBUG=/tmp /home/joe/my_disam_bin/disamnet
util/dswabnet.c is a simple wrapper around util/disamnet.c which defines ISOTHERENDIAN, which in turn produces a binary which will automatically reorder the bytes in everything it knows to be an integer.
This includes all parameters and official structures, such as keydesc and dictinfo, etc, but expressly does not touch data records. disamnet is designed to compress and otherwise efficiently transmit data without loss, but endian order in records is presumed to be handled on a higher level.
While it remains feasible to provide an automatic switching server, able to handle either sort of client, should this be required, it is slightly more efficient, after all considerations, to run a dual binary setup.
It is left up to the server administrator to decide which end is up, and
to assign a different port number to clients of each order, in order to
ensure that clients of the other
order will connect to dswabnet, which
will translate for them, and clients of the same order as the server must
connect to disamnet, which does not.
Clients will return ENETORDER error when connected to wrong ended servers.
ISAM files are stacked on common hosts, and only one connection per port per host is allowed - meaning you can open any number of files across a number of different servers, each of which will only be connected once, if at all.
For TCP/IP hosts this is based on the IPv4 address after gethostbyname(3) lookup, and as such should not be confused by aliases and mixed notation.
Pipe calls, like ssh, on the other hand, only pass on the address string they are given, and this must therefore match exactly - case and all - or will cause redundant extra connections and server processes.
Host connections are automatically closed when the last associated isam file is closed, and will be reopened again, as needed. If this should result in too much overhead in your application, or otherwise causes any trouble, please contact support - mitigation is probably a simple matter of implementing an appropriate strategy - including disabling the feature outright - depending on the situation.
isrename will return EBADADDR unless both names are on the same server.
iscopy will return EBADADDR unless both files on are on the same server.
If isclone is passed a network destination file name, and if the server on which the source file is hosted can connect to the destination server, the operation should work as expected.
The isCheck and ischeck series of functions will work over disamnet, and the dcheck utility is able to check and rebuild remote files, but is not able to display the additional header details normally shown.
Audit files are stored on the assocated isam file server.
DISAMNET is available through both the base and wrapper (cisam standard) interfaces, but please note your application may no longer compile if you have been using various internal fields within the disam file structure.
Please see the IsamFile structure in isbase.h for the changes, and note that the bulk of this structure has been hidden behind ISDANGEROUS.
These fields are only available in local files, and the entire structure is different for remote files, from ISDANGEROUS through to the end.
As long as the isam->where integer has a value of zero, the file is local, and these fields are safe to access, but if there is any chance the file might be remote, your application should check before proceeding.
The fields above ISDANGEROUS are common to all sources, and are maintained in sync with the source files on the remote server.