TCPAuth Manual

TCPAuth is a server process which runs authent modules and provides a TCPIP PORT interface to it's client External Authentication Module. 

TCPAuth has two parts:

  1. tcpauthsvr - the TCPIP server, which runs your authentication module and hence provides TCPIP access to your database.
  2. tcpauth - the client to the TCPAuth Server. It is an authentication module which talks to tcpauthsvr, but in other ways behaves just like a normal NetWin authent module.

Because the client and server communicate via TCPIP, TCPAuth may be a good option for systems that have a cluster of servers which need access to the authentication module, e.g. the DMail servers, DSMTP, DPOP and IMAPD, and also, if you are running the NetAuth product on a web server, on a separate box.

By using the TCPAuth Server, transitory processes like IMAPD, which is spawned for each connection, can authenticate quickly, even if your authent module itself takes several seconds to start.

This module is available for both Windows and UNIX platforms, so it also has the great advantage that you can run the server on one platform (where your database is located) and the client on another platform.

On this page ...

Useful links to other pages ...



TCPAuth Installation - UNIX

uncompress tcpauthVERSION_PLATFORM.tar.Z
tar -cvf tcpauthVERSION_PLATFORM.tar
cd tcpauthtemp
./tcpauthsvr -install

You will probably need to modify /etc/tcpauthsvr.conf in order to make it run your real authent module, e.g.

authent_process /usr/local/dmail/your_module_name

You must restart the TCPAuth Server in order for any change to the config file settings to take effect.

You can simply kill the server process to stop it, and use,

./usr/local/dmail/tcpauthsvr_start.sh

to start it again.

You must then add to your rc.local script or similar, this line:

./usr/local/dmail/tcpauthsvr_start.sh

so that the server is started on startup.

In order to see whether it is running ok, examine

/usr/local/dmail/tcpauthsvr.log



TCPAuth Installation - Windows

Run the self extracting archive,

tcpauthVERSION.exe

which will then run the server with the -install command,

c:\dmail\tcpauthsvr -install

The -install option will make the server install itself as a Windows Service, on platforms which support that. Therefore, in order to stop and start the server you MUST go to your Control Panel, and then the Services dialog, and find tcpauthsvr, 'TCPAuth Server, Network User Database' in the list of services. Following this, use the Start/Stop button to control the TCPAuth service.

The install also copies the tcpauth.dll file into your system32 directory for the TCPAuth client to use.

You will  probably need to modify c:\winnt\system32\tcpauthsvr.conf in order to make it run your real authent module, e.g.

authent_process /usr/local/dmail/your_module_name

You must restart the TCPAuth Server in order for any change to the config file settings to take effect.

In order to see if it is running ok, examine

c:\dmail\tcpauthsvr.log



Testing TCPAuth Server after Installation

In order to test it, run the TCPAuth client module by hand. You should find that the installation has copied both the TCPAuth Server,

tcpauthsvr

and the TCPAuth client,

tcpauth

executables to your dsmtp_path directory, e.g.

c:\dmail\

on Windows platforms, and,

/usr/local/dmail/

on UNIX based platforms.

So, given that the user database has a user with the username 'username', you can enter at a (MS DOS) command prompt,

./tcpauth (or c:\dmail\tcpauth on windows machines)
lookup username
+OK username config 0
check username password
+OK username config 0
quit

NB: if you have set authent_domain to true in dmail.conf, your user database will have usernames like,

username@domain

so replace 'username' with 'username@domain' in the example above.


TCPAuth Client Installation - all platforms

Once you have tested the TCPAuth server by running the client, you will then need to configure the programs that previously authenticated against your authentication module so that they run the TCPAuth client instead.

The examples below assume that your TCPAuth Client is located at,

c:\dmail\tcpauth.exe

If you are on UNIX platforms substitute with,

/usr/local/dmail/tcpauth

or whatever your path is.

NB: If you are running the client on a different machine from the server, please see the notes below.

DSMTP and DPOP:

Add or edit the authent_process line in your dmail.conf file (typically /etc/dmail.conf or c:\winnt\system32\dmail.conf) to read,

authent_process c:\dmail\tcpauth.exe

Then restart both DSMTP and DPOP.

IMAPD:

Add to dmail.conf,

imapd_authent_process c:\dmail\tcpauth.exe

NetAuth:

Add to netauth.ini,(you may want to choose a different path if you don't have dmail on the machine where you run netauth)

authent_process c:\dmail\tcpauth.exe

Notes for running TCPAuth client on a different machine to the server:

If you are running the client on a different box to the TCPAuth Server, then you need to give the '-host' command line option,

c:\dmail\tcpauth.exe -host x.x.x.x

where x.x.x.x is the IP address of the machine running your TCPAuth Server.

Also, note that you MUST copy the encryption file from the server machine to EVERY machine running the client, see,
Secure TCPIP connection for details.

If the client is running on a windows machine then you must also copy the file,

c:\winnt\system32\tcpauth.dll directory

to the system32 directory on the machine which will run the TCPAuth client.


Secure TCPIP connection

TCPAuth Server and Client automatically encrypt communication between themselves if they are on the same machine.

If you are running the client on a different machine, you must copy a file from the server machine to the machine running the client. The file you will need to copy is,
on Windows:

c:\winnt\system32\xlate.dat

on Unix:

/etc/xlate.dat

and you need to place it in one of those two locations (whichever is relevant for the Operating System) on the machine running the TCPAuth client. The file can be transferred in ASCII mode between NT and UNIX boxes. You may need to overwrite the file which you find there.


Windows Users Gotcha! TCPAuth Server Runs as System...

Note these three important things on Windows NT, Windows 2000, and TCPAuth Server ...

1. will be running as a Service.

2. will also be set to run as the 'system account'.

3. defaults to c:\winnt\system32 as the 'home directory' for any authent module which it runs.

So, you will need to ensure that your authentication module can find it's configuration file if it has one, and that it can run as the 'system account' user.

You can set the TCPAuth Server to run as another user account, e.g. where it needs to access a shared network drive, but this is not recommended unless you need to.

Here are some specific details for some authentication modules...

NWAuth:

You may need to use the command line option, -path, in order to ensure that it can find the correct working directory. If so, set in c:\winnt\system32\tcpauthsvr.conf,

c:\dmail\nwauth.exe -path c:\dmail

and restart the TCPAuth server. This will ensure that nwauth finds, for example, one of it's user database files, c:\dmail\nwauth.txt .

ODBCAuth:

ODBCAuth requires you to have set up a ODBC data source (see the icon in your system control panel). In order to allow the 'system account' to access this file, you must create the data source as a 'System Data Source' rather than as the default, 'User Data Source'.

Also, you should ensure that your odbcauth.ini file is located at,

c:\winnt\system32\odbcauth.ini

rather than,

c:\dmail\odbcauth.ini



TCPAuth Server Config Settings - tcpauthsvr.conf

Setting Example Default Required Function
authent_number authent_process 5 1 no Specifies the number instances of the authentication module which the TCPAuth server should run. We recommend 3 or 4. NB: If you set it higher than 10 the server will not run.
authent_process authent_process c:\dmail\nwauth.exe -path c:\dmail (none, which means that nwauth is the database) no Allows you to specify an authentication module to be run as the database 'backend' rather than nwauth.
log_dir log_dir c:\dmail\log (homedirectory) no Allows you to specify a directory for the tcpauthsvr.log file other than c:\winnt\system32 or /usr/local/dmail
debug debug true false no If set, the log file will contain debug level (detailed) information.
secret_file secret_file c:\dmail\work\xlate.dat c:\winnt\system32\xlate.dat or /etc/xlate.dat no Allows you to specify a non-standard secret file for encrypting the TCPIP sessions. Both the server and the client must be using a copy of the same file.



Un-installing TCPAuth

If you need to un-install the TCPAuth server, simply run the server with the -uninstall option, e.g.,

cd c:\dmail
tcpauthsvr -uninstall





 

Products Downloads Prices Support Company