TCPAuth is a server process which runs authent modules and provides a TCPIP PORT
interface to it's client External Authentication 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.
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.
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.
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.
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
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 /usr/local/dmail/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.
|
If you need to un-install the TCPAuth server, simply run the server with the -uninstall option, e.g.,