taRadiusSrv v2.5 Technical Documentation

(Für deutsche Fassung hier klicken)

This is the technical documentation of taRadiusSrv version 2.5. The change history can be found here.

taRadiusSrv Installation

To install taRadiusSrv follow the documentation in install-en.html.

Setting up / customizing taRadiusSrv

There are the 5 scripts (in the sub-directory 'data') below to customize. Do not change their name or location, or they won't work anymore. Make sure that the scripts execute without prompting the user for an input!

Starting taRadiusSrv

eve taRadiusSrv.eve [-c | -a]
or:
java -cp eve.jar Eve taRadiusSrv.eve [-c | -a]
   -c: start in Console-Mode
   -a: start in Administration-Only-Mode

In Console-Mode the RADIUS server runs without GUI. All output is sent to the console (stdout). This mode is meant for Linux systems that do not support graphics.

In Administration-Only-Mode no RADIUS requests are handled. This mode can be used to configure the RADIUS server from a PC via network share (e.g. for Linux systems, that only support the Console-Mode).

Configuring taRadiusSrv

Before you can configure taRadiusSrv you must login as admin first. On Linux, first stop the daemon process of taRadiusSrv (evecl) and start the GUI version (eve taRadiusSrv.eve). Click on the 'Admin' button and enter the admin password. If the password is correct, you are logged-in and the admin window is shown. The admin window is closed automatically after 5 minutes of inactivity. On Linux, you should stop the GUI version and start taRadiusSrv as daemon again.

When you enter the admin GUI the first time after the installation, the admin password will initially be set to _admin
You should now immediately change the admin password by setting the password of the user _admin to ensure that only authorized persons can access the admin GUI!

The admin GUI runs in its own thread. That means that the server will continue to handle requests while you are configuring it. Changes are immediately active, once you have entered them (exception: Server ports and language, see below).

The 'Debug mode' can be activated through the menu to troubleshoot RADIUS problems. In this mode all incoming and outgoing RADIUS packets are displayed on the screen in raw and interpreted format. The debug mode is automatically deactivated again when the admin GUI is closed.

Defining server settings

To define server settings, click on the 'Settings' tab.



The 'Server port authentication' is usually 1812 - change only if there is a good reason. If you change the server port, you need to restart the RADIUS server before the change becomes active.

The 'Server port accounting' is usually 1813 - change only if there is a good reason. Set it to 0 to deactivate RADIUS Accounting. If you change the server port, you need to restart the RADIUS server before the change becomes active.

If a user has more than consecutive 'Max unsuccessful logins', the server locks the user account and sends a message to the user and to the admin.

The tokens sent by the server become invalid after 'Max token lifetime' minutes.

With 'Nr. of log lines in GUI' you can define how many log lines should be displayed in the text area of the GUI's main window.

With 'Nr. of lines in HTML Log' you can define how many log lines should be displayed in the file html/index.html. You will always see the last n log lines of the main text field.

If you un-check 'Log _monitor user' then the server will not log the authentication requests of the '_monitor' user.

'Warn x users before max' will tell the admin when he is reaching the limits of his license. If this value is set to 3 and the license allows 10 users, the warning will appear when adding the 7th user.

With 'Language' you can select one of tha available languages. You need to restart the RADIUS server to activate the new language. You can add more languages yourself. For this, get yourself a copy of the language pack (taRadiusSrv-custom.zip) and install it as described here.

'Update databases' is only used after installing a new version of taRadiusSrv and then only if the update documentation says so. It does not harm the system if you accidentally press the button, though.

Clients and users

Clients are computer systems that are allowed to use the RADIUS server's authentication service. Users are persons that can use the RADIUS server to login to the clients. There are no groups (yet). So, all users can login to all clients if the authentication is correct.

Managing clients

To manage clients, click on the 'Clients' tab. You get a list of all allowed clients. The list can be sorted ascending or descending by clicking on the table headers.

There are following buttons:

Add clients

To add a new client, click on the 'Add' button.



The 'hostname' is the name of the client machine. It does not need to match the real hostname, it is rather informational only. The hostname is case-sensitive and must be unique.

The 'IP Address' is the IP address of the client machine, as seen by the RADIUS server. The IP address must be unique.

The 'Shared secret' ensures that no unauthorized client can use the server. It must be defined in the RADIUS config of the client also.

Under 'Remarks' you can enter any descriptive text.

Managing users

To manage users, click on the 'Users' tab. You get a list of all allowed users. The list can be sorted ascending or descending by clicking on the table headers.

There are following buttons:

Add users

To add a new user, click on the 'Add' button.



The 'Loginname' is case-sensitive and must be unique. It is the unique identifier for a user in the database.

'Last name' and 'First name' are informational only.

The 'Password' of the user is mandatory.

The user account can be locked and unlocked manually by the admin ('User is locked'). The account is automatically locked by the server after too many failed login tries.

The user account can be set to expire automatically at a certain date ('Account expiration'). From then on, the user will not be able to login, but the server will send him a message saying so.

The ('Framed IP address' ) defines, which (private) IP address should be assigned to the VPN-Client. 255.255.255.255 means that the client can choose its address itself. 255.255.255.254 means that an address should be automatically assigned from a server pool.
If a 'Framed IP address' is defined for a user, following RADIUS attributes are also returned automatically: Service-Type=Framed und Framed-Protocol=PPP

The 'Authentication method' defines how the user must log in. In the 'Password only' mode, no tokens are needed and only the password is verified. THIS MODE IS NOT RECOMMENDED BECAUSE IT EXTREMELY WEAKENS THE ACCESS SECURITY !!! In the 'Send token' mode, the user first logs in with only his password. This first try is always rejected by the server, but if the password is correct, the server generates a token and sends it to the user. The user then logs in a second time, this time with password+token. In the 'TOTP' mode, the user generates a token with an app (e.g. Google Authenticator or FreeOTP). He then logs in with password+token.

'Address 1', 'Address 2' and 'Address 3' can be active (checked) or inactive (un-checked) and are used to send the token to the user by calling the respective script (taRadiusSrv-SendTokenX.cmd). The addresses can be anything you specify, e.g. an email-address or a handy/pager number. How these addresses are used to send the token to the user is up to the scripts.

In the 'TOTP' area you can define the TOTP parameters. Google Authenticator uses HmacSHA1 with 6 digits and a time interval of 30 seconds. In FreeOTP these values can be freely chosen. With the button 'New key', a new key is generated and shown in the prompt. This key must be entered in the app, so that the server and the app generate the same series of tokens. If you use a hardware device with an unchangeable key, you can enter this key here (Base32 encoded) instead of the proposed one. With the 'Test' button you can test afterwards if the app (or the hardware device) and the server generate the same token.

Under 'Remarks' you can enter any descriptive text.

Monitoring taRadiusSrv

The server logs all requests and all admin actions in the taRadiusSrv.log file. This file is in the taRadiusSrv program directory and only the admin (and the server of course) should have access to it.

The last 30 lines (configurable) of the log file (without admin actions) are written to html\index.html and can therefore be viewed with a web browser if the web server is configured accordingly.

If you want to actively test if the server is still working, you can use the special built-in user '_monitor' (you can use any password you like). This user will always be denied access, but by getting an negative answer you know that the server is still responding. You can suppress these monitoring requests in the log (see settings).

Extending the license

When your users database grows and the license becomes too small, you can replace your license with a bigger one. Follow these steps:

  1. Contact Tanapro GmbH and purchase a bigger license.
  2. Send a copy of your old license file (taRadiusSrv.license) of the software to Tanapro who will create a new license file and send that back to you.
  3. Rename your old license file, so it does not get overwritten (just in case there is a problem with the new license, so you could revert back).
  4. Copy the new license file into the subdirectory 'data' of taRadiusSrv.
  5. Restart the RADIUS server.