TCPAuth is a server process that 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 that 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 to make it run your real authent
module, e.g.
authent_process /usr/local/dmail/your_module_name
You must restart the TCPAuth Server 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.
To see if it's 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 that
support that. So 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. Then 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 to make it run your real authent
module, e.g.
authent_process /usr/local/dmail/your_module_name
You must restart the TCPAuth Server for any change to the config file settings to take effect.
To see if it's running ok examine
c:\dmail\tcpauthsvr.log
Testing TCPAuth Server after Installation
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 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 true, in dmail.conf then 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 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, then 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 that 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 then you must copy a file from the server machine to the machine
running the client. The file you 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 that you find there.
Note these three important things, On Windows NT, and Windows 2000, 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 that it runs.
So you 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, to ensure 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 ione of its user
database files,
c:\dmail\nwauth.txt .
ODBCAuth:
ODBCAuth requires that you have set up a ODBC data source (see the icon in your system control panel).
So that the 'system account' can 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 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 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, then simply run the server with the -uninstall option, e.g.,