OpenVPN ALS SSL-VPN on Debian Squeeze 32bit (Adito)
This documentation will be constantly updated. If I have a problem with my Adito server and can solve it, I will post the solution here. If you have additional information, feel free to contact me by mail: pcfreak - at - pcfreak - dot - de
History
OpenVPN ALS is based on “SSL-Explorer” by “3SP Ltd”. The product was first released on the SourceForge.net website in August 2004 and has since had over 275,000 downloads of the main product distribution as of December 2007. All versions of the core Community Edition product were licensed under the GPL while the commercial Enterprise Edition product, which was built upon the Community Edition but with additional functionality, was licensed separately under a commercial license. A fork of the last GPL release has been created named Adito, which was later renamed to OpenVPN ALS.
Around March 2008, 3SP Ltd announced that they discontinued development of the Community Edition.
As with any product previously licensed under the GPL, the source code is still available via SourceForge.net. However, future updates to the source code or pre-built binaries will not be forthcoming from 3SP Ltd.
As of November 18, 2008, 3SP Ltd. is now part of Barracuda Networks. The technology behind SSL-Explorer is now incorporated into the Barracuda SSL VPN.
A lot of people use OpenVPN ALS but there is not much development since 2008.
Linux Setup and Preparation
We just install the 32bit Edition of Debian Linux 6.0.3 (Squeeze) with 2 network connections in English language with English locale settings, the standard system utilites and SSH server.
Hostname: openvpnals Domain : yourdomain.com
The hostname in this documentation is “psliovpnals”
Because we need Oracle's Version of JAVA we need to enable additional sources in /etc/apt/sources.list Add the following lines at the end of /etc/apt/sources.list
# non-free deb http://ftp.de.debian.org/debian/ squeeze non-free deb-src http://ftp.de.debian.org/debian/ squeeze non-free
Before we continue we bring the system up to date:
apt-get update apt-get upgrade apt-get dist-upgrade
Additionally we install the following packages as prerequisites for our later install of OpenVPN ALS.
apt-get install sun-java6-jre sun-java6-jdk subversion ant zip unzip
The packages will install with all the necessary dependencies and will require about 252 Mbyte of disk space.
To setup “sun-java6-jre” as the default JRE we have to execute
>update-alternatives --config java There is 1 choice for the alternative java (providing /usr/bin/java). Selection Path Priority Status ------------------------------------------------------------ 0 /usr/lib/jvm/java-6-sun/jre/bin/java 63 auto mode * 1 /usr/lib/jvm/java-6-sun/jre/bin/java 63 manual mode
and select the correct number (in this case 1) for java-6-sun. - Do the same for javac
>update-alternatives --config javac There is 1 choice for the alternative javac (providing /usr/bin/javac). Selection Path Priority Status ------------------------------------------------------------ 0 /usr/lib/jvm/java-6-sun/bin/javac 63 auto mode * 1 /usr/lib/jvm/java-6-sun/bin/javac 63 manual mode
Now the system knows, that it should use “java-6-sun” for java and javac
Download OpenVPN ALS from SVN trunk
The latest community based version of OpnVPN ALS including a working RADIUS plugin can be downloaded from sourceforge.net via subversion. Make sure you have a direct internet connection at this point since svn does not natively support proxies. If you are online, execute the following command:
svn co https://openvpn-als.svn.sourceforge.net/svnroot/openvpn-als/adito/trunk /opt/openvpn-als
to download the entire SVN trunk to /opt/openvpn-als. It will fill about 200 MBytes on your hard disk.
Install adito
Adito is the server part of OpenVPN ALS. Jump to the folder /opt/openvpn-als and run the following command to see all available options:
>ant -projecthelp Buildfile: /opt/openvpn-als/build.xml Main targets: clean Removes compiled files compile Compile Adito. console Starts the Adito server in the foreground display all output to the console dist Create an executable, ready to distribute version of Adito help Displays some help. install Run the Adito installation wizard. The server must not be running. install-agent Install Adito Agent. install-service Install Adito as a service. javadoc Generate javadocs for everything start Starts the Adito in the background start-using-java Starts the Adito in the foreground without the OS-dependent wrapper stop Stops the running Adito. Note, this currently does not work on all platforms. sysinfo Display some system information uninstall-service Uninstall Adito service. Default target: start-using-java
Now we know what to execute to install openvpn-als, the agent and the service.
The “install” command compiles all sources and initiates the installation wizard:
cd /opt/openvpn-als ant install
You will see a lot of messages, monitor them exactly and make sure that the result (end of output) looks like this:
... ... a lot of lines before here install: [mkdir] Created dir: /opt/openvpn-als/adito/tmp [java] Starting installation wizard......Point your browser to http://openvpnals.yourdomain.com:28080. [java] [java] Press CTRL+C or use the 'Shutdown' option from the web interface to leave the installation wizard. [java] .
If so, you can now open the web-interface on http://ip-address-of-your-server:28080 and continue with the setup.
I will just show the default steps here, please make sure you change them to fit your needs:
Initial Setup Wizard via web interface
- Step 1 - Set Keystore Passphrase –> “y0urKeyStorePassPhrase”
- Step 1 - Create New Certificate
Host name : openvpnals Organisational Unit: Freak Company : PCFreak City : MyTown State : Bavaria Country Code : DE
- Step 2 - Configure User Database
[ ] Active Directory [x] Built-in [ ] UNIX
- Step 3 - Configure Super User
Username: SuperUser Email : email@domain.com Password: @dmin!.$$$$
- Step 4 - Configure Web Server
Port : 443 Protocol : http Listening interfaces : Remove All Interfaces and only select the interface with the external IP Valid external hostnames: openvpnals.yourdomain.com Invalid hostname action : Redirect to valid hostname (or whatever you like) * Step 5 - Configure Proxies
We have no proxy to use at this point. * Step 6 - Summary
Press Finish here and wait until everything is done. Then click the “Exit Install” button. Wait a moment, after a few seconds the installer will exit and you will see the following output on the console:
BUILD SUCCESSFUL Total time: 2 minutes 13 seconds
The server side of OpenVPN ALS ist now installed.
Install adito-agent
Adito Agent is the client part of OpenVPN ALS that is needed for tunneling. You don't need it, if you just publish network places or Web Forwards with OpenVPN-ALS but as many people say: “Adito is nothing without it…”, I recommend to build it anyway.
cd /opt/openvpn-als ant install-agent
Again you should have a lot of output lines ending with:
... ... a lot of lines before here release: [zip] Building zip: /opt/openvpn-als/adito-agent/build/release/adito-agent.zip [copy] Copying 1 file to /opt/openvpn-als/adito/conf/repository/archives BUILD SUCCESSFUL Total time: 28 seconds
Install adito as a daemon
On Linux you have to fix 1 configuration file to make the daemonize script working correctly!
In your adito install dir, find and modify wrapper.conf.base, usually it is located under
/opt/openvpn-als/adito/conf/wrapper.conf.base
Locate these lines
# Java Additional Parameters # file.encoding forces the file encoding in java process in wrapper, # but in adito when you launch server without wrapper (start-using-java) # the file.encoding is taken from java runtime, on windows it is cp1252. # encoding is use when you login and when you change password. # if you launch server using wrapper, you change your password. # you stop server, and start-using-java with different file.encoding, you cannot login. # It cause some problems if encoding are different. #wrapper.java.additional.2=-Dfile.encoding=UTF-8
Remove the # so it looks like
wrapper.java.additional.2=-Dfile.encoding=UTF-8
and save. If you already installed the service and you have to fix this, just do the same in /opt/openvpn-als/adito/conf/wrapper.conf and restart the service.
I found this info at http://ubuntuforums.org/showthread.php?t=1345128 and the idea was from http://wiki.amahi.org/index.php/Adito. It worked!
After fixing the daemonize script we can now safely execute the following command:
cd /opt/openvpn-als ant install-service
with the following result:
... ... a lot of lines before here install-service: [echo] Installing Adito as Linux service [exec] Detecting Java [exec] Using /usr/lib/jvm/java-6-sun-1.6.0.26/jre [exec] Detected OS debian (x86) [exec] update-rc.d: using dependency based boot sequencing [exec] insserv: warning: script 'adito' missing LSB tags and overrides [exec] Service installed [echo] Adito installed as Linux service BUILD SUCCESSFUL Total time: 39 seconds
It is now possible to use the following startup options for /etc/init.d/adito:
console | start | stop | restart | status | dump
At this point we will not start the service as a daemon, we execute it from the console with the following command:
cd /opt/openvpn-als ant console
This should result in:
Buildfile: /opt/openvpn-als/build.xml console: create-wrapper-conf: [copy] Copying 1 file to /opt/openvpn-als/adito/conf [echo] Creating wrapper configuration dynamically [echo] [echo] Java executable: /usr/lib/jvm/java-6-sun-1.6.0.26/jre/bin/java [echo] Wrapper directory: install/platforms/linux/x86 set-tools: check-tools: check-permissions: console: [exec] Running Adito...
We can now jump to the webpage (https://openvpnals.yourdomain.com) and login with the super user account to do other configurations.
Customizing
Extensions
Lars Werner has a good Adito appstore for his special version he created for windows. You can mirror the store to your local hard drive and then use the extension if you like:
wget -mir "http://adito.werner.no/appstore/"
Create your own Extension Store
To create your own Extension Store, you just have to host a xml file on a website under the following structure:
http://yoururl/appstore/<your version number>/store.xml
that looks like this (This sample is from Lars Werner's Appstore):
You just have to set 2 configuration options in adito/conf/system.properties
The version number “adito.forceVersion”
# You can force Adito to identity itself as a different version for # extension updates adito.forceVersion=0.9.1
and the appstore location
# The location (either a URL or a file path) of the application store. #adito.downloadableApplicationStore.location=http://www.aditoproject.org/appstore/ #This points to my Dropbox public folder adito.downloadableApplicationStore.location=http://dl.dropbox.com/u/6828xx/adito/appstore/
Please make sure, that you have the correct folder structure and the correct version number. You can use Lars Werner's Appstore as a good starting point, or just use his appstore with your installation, by just changeing the 2 configuration options abofe in your configuration file.
Since the location can also be a file-path you could place the files locally but I could not find out how to get that working.
Also take a look at the following document How_to_create_an_Adito_Extensions_Store.mht
Logo
You can configure a custom logo for the logon page by copying an image file to [adito]/conf/site/icons and then choose it from System Configuration → Security Options → Logon Page.
If you used this documentation, the path on your linux box will be:
/opt/openvpn-als/adito/conf/site/icons#
If the directory does not exist simply create it. Once the logo has been uploaded to that location, you will be able to select it in the dropdown. That is all you need to do. This works for GIF, JPG, PNG and BMP file types.
White Background for pageHeader
The Adito Navbuttons (top-right) have a small white border, so they look ugly on the black background. By changing the file
/opt/openvpn-als/adito/webapp/theme/default/componentStyles.css
you can get a much cleaner look. Comment out the original value (black) and add the new one (white):
div#component_pageHeader { font-family: Tahoma, Arial, Helvetica, sans-serif; width: 100%; height: 50px; margin: 0px 0px 0px 0px; padding: 0px 0px 0px 0px; background-image: url(images/banner.gif); background-repeat: no-repeat; /* background-color: black;*/ background-color: white; color: white; vertical-align: middle; }
div#component_smallPageHeader { ^M font-family: Tahoma, Arial, Helvetica, sans-serif; ^M width: 100%;^M height: 35px;^M margin: 0px 0px 0px 0px;^M padding: 0px 0px 0px 0px;^M background-image: url(images/banner-small.gif);^M background-repeat: no-repeat;^M /* background-color: black;*/^M background-color: white;^M color: white;^M vertical-align: middle;^M
More Customizing
There's only a limited amount of customization that is possible from within the Adito interface and that relates to adding a logo and text to the logon page.
For further customization this is manual and not officially supported. Look for CSS files in the adito\webapp\theme\default directory, you should be able to see settings that affect global colours etc in there.
You will also see image files under the same theme directory if images need to be replaced.
There is something else which can be looked at for a quick fix to alter some colours, but please note that this may not be fully supported any more even though the entries are still there.
If you look at the adito/conf/system.properties, you will find a lot of entries starting with:
#adito.defaultTheme.
If you uncomment all these lines, you end up with a mostly green looking theme, so you could get an idea if changing any of those values might do what you require.
Administration
Manipulating the database
Adito uses a HSQL Database to store configuration parameters like user accounts and passwords.
You should NOT install the package “hsqldb-utils” on your Linux box, since the newer versions might be incompatible with Adito. Instead look for the file “hsqldb.jar” on your machine and use it, later.
There are two ways to read/write from/to the database:
- access the database file (Adito is stopped)
or
- enable the HSQLDB TCP/IP Server and access the database (Adito is running)
Create sqltool.rc for database connection
For both methods you should create a configuration file (sqltool.rc) in the home directory of the connecting user with the following content. (Adjust the paths for your local installation of Adito). If you don't like a configuration file lying around, feel free to specify all parameters at the command line.
#TCP/IP urlid explorer_tcp url jdbc:hsqldb:hsql://localhost:9001/explorer_configuration username sa password # FILE urlid explorer_file url jdbc:hsqldb:file:/opt/openvpn-als/adito/db/explorer_configuration username sa password
Connect via TCP/IP
By default you cannot access the database via TCP/IP. You have to enable the hsqldb TCP/IP-Server to be able to connect via TCP/IP. Change the following line in /opt/openvpn-als/adito/conf/system.properties from “false” to “true”:
adito.hsqldb.tcpipServer=false
If you have prepared your connection file, you can now connect to the database with the following command (Adito is running):
java -jar /opt/openvpn-als/adito/webapp/WEB-INF/lib/hsqldb.jar --debug explorer_tcp
Connect opening the datbase as a file
If you have prepared your connection file, you can now connect to the database with the following command (Adito is not running):
java -jar /opt/openvpn-als/adito/webapp/WEB-INF/lib/hsqldb.jar --debug explorer_file
If you get an error:
Failed to get a connection to jdbc:hsqldb:file:/opt/openvpn-als/adito/db/explorer_configuration as sa. The database is already in use by another process: org.hsqldb.NIOLockFile@177f3e7b......
then you forgot to stop Adito.
Useful SQL queries and commands
\dt get a list of existing tables \d [TABLENAME] get the scheme of table TABLENAME SELECT * FROM TABLENAME; show the content of table TABLENAME
SQLTool does not automatically write changes to the disk. You need to do a commit after your changes:
sql> COMMIT;
If feel lucky, you can simply set autocommit to true:
sql> \a true Auto-commit is set to: true
Updating the password in hsqldb database
Adito stores the user passwords internally in the table USERS. You can get a user and corresponding password (a base64-encoded md5 hash) by saying:
sql>select username, password from users where username='johirv';
Adito stores a function (a stored procedure) named ENCPASSWORD in hsqld. You can use this function to update a users password straight in the database by issuing something like:
sql>update users set password=ENCPASSWORD('qwerty'), last_password_change='2007-03-18' where username='johirv';
If you encounter issues using the ENCPASSWORD function because the DB is offline you can just use the following command to enter the following hash which sets the password to 'password'
sql>update users set password='X03vv707Wu+/vWXvv70d77+9J96477+9z5k=' where username='johnirv';
Re-enabling a permantly locked account
If you manage to lock your admin user permanently out of Adito, you need to manually remove the account lock. First stop Adito (if using embedded DB) and connect to the database (see above). Then check the row containing the lock:
sql> SELECT * FROM ATTRIBUTES; PROPERTY_CLASS CLASS_KEY ATTRIBUTE_NAME ATTRIBUTE_VALUE -------------- --------- ----------------------------- --------------- userAttributes admin_1 aditoUserEnabled false 1 rows
And then delete it (maybe you will have to adjust the CLASS_KEY param to match your username):
sql> DELETE FROM ATTRIBUTES WHERE CLASS_KEY='admin_1' AND ATTRIBUTE_NAME='aditoUserEnabled'; 1 row updated
Next verify that the operation was successful:
sql> SELECT * FROM ATTRIBUTES; PROPERTY_CLASS CLASS_KEY ATTRIBUTE_NAME ATTRIBUTE_VALUE -------------- --------- ----------------------------- --------------- 0 rows
Make sure you take a look at the Wiki-Page concerning Adito database management, too: http://sourceforge.net/apps/trac/openvpn-als/wiki/database_management
Re-enabling the Default Authentication Scheme when you lock your Super User out of Adito
In the event that you inadvertantly lock your Super User, or any other account out of Adito you can use the following instructions to reactive the Default Authentication Scheme and allow login through that scheme:
Shutdown your Adito service and connect to your database via file using HSQLDB.
After login run the following SQL command:
UPDATE AUTH_SCHEMES SET ENABLED = '1' WHERE RESOURCE_NAME = 'Default';
This process will re-enable the Default password only authentication scheme.
Insert a new user (you know the encrypted password)
insert into USERS (USERNAME,EMAIL,FULLNAME,LAST_PASSWORD_CHANGE,PASSWORD,REALM_ID) VALUES ('superuser', 'your@email.com', 'Super User', '2012-03-02', '<encoded password>', '1');
Insert a new user
insert into USERS (USERNAME,EMAIL,FULLNAME,LAST_PASSWORD_CHANGE,PASSWORD,REALM_ID) VALUES ('superuser', 'your@email.com', 'Super User', '2012-03-02', ENCPASSWORD('<password>'), '1');
Some interesing queries
sql> select * from SYSTEM_ALIASES; sql> select * from SYSTEM_ALIASES where OBJECT_NAME like '%adito%'; sql> select * from EXPLORER_PROPERTIES; sql> select * from EXPLORER_PROPERTIES where KEY_1 like '%priv%'; ...
Managing Accounts
To start creating users, log in to Adito using the super user that was configured during the installation of Adito (when you connected to http://servername:28080). Make sure you see “Management Console” on the left side underneith the “Adito VPN” title. If you don't see it, click on the third icon from the right in the top right corner.
Within the Management Console pane, click on “Accounts.” This will list all the accounts that currently exist. (If you pointed this to Active Directory, it *should list all the users it found.) From here, you can enable / disable accounts, delete accounts, create accounts, edit accounts …. If you point it to Active Directory in the future sometime, you *will have to do all the user configuration within AD except for the enable and disable part which is still handeled by Adito (there's a small chance you can do it from within Adito, but I'm not 100% sure).
To create new users, click the “Create Account” link in the top right corner. This wizard will drive you through the process of creating accounts. When I created a test user, it created it disable, so to enable it, click on the “more” link for your newly created user within the “Accounts” section and choose “Enable.”
Once you get all your users created, you should look into grouping them together for easier managment. Click on “Groups” in the left management panel and start creating groups. You can skip this step as the policy stuff discussed later can be comprised of individual users as well as groups.
Then, you can start with creating policies. I think of a policy as a glorified group - but it is requried when assigning access to resources and system rights. And, this comes in handy when multiple groups are allowed to do an action, in which you would only need to add the policy to the action being allowed.
The “Access Rights” link in the left hand management panel lets you designate permissions to stuff. This is where you match system polices to actions / functions. You have the choice between system, resource and personal rights. If you're concerned about creating additional administrators, choose the “create sytem right” in the top right corner.
Problem: Private Key Passphrase Required
Adito stores user attributtes in the internal HSQL-Database. The attributes will be encrypted with the public key of the user and then stored in the database. This means you can only decrypt the attributes value with the private key of the user.
In
System Configuration --> Security Options --> Confidential Attributes --> Confidential Mode
you can select the protection level of the users private key. You can select 3 values:
- Disabled
Confidential user attributes will not be encrypted.
- Prompt
Confidential attributes will be encrypted with the users private key. If there is no password for the private key set (not the user password), the user will be prompted for a password to protect his private key.
- Automatic
The password for the private key will be automatically set to the value of the users logon password. If the user did not specify a logon password, he will be asked for it at the next logon.
This could cause a lot of problems. After 28 days (Days before expiry in Password Options) the user will be prompted to change his password. If the “Confidential Mode” is set to “Prompt” the user will not only be asked to change his password, after that he will be prompted for the existing password for his private key. If the user forgot his password, he can no longer login!
In an environment, where an administrator sets up the user accounts and the authentication uses One-Time-Passwords via RADIUS you should think about setting the “Confidential Mode” to “Disabled” to make sure that you have no such problems.
If you use OTPs and still want to encrypt the users attributes, you could set the “Days before expiry” in the password options to a high value (eg. 3650 = 10 years), so the users do not need to change their password and since you use OTPs it is no problem. Also set the “Confidential Mode” to “Automatic”. Make sure you set a strong password for the user, since it will not change the next 10 years!
Solution if the user has forgotten his private key password
If you get the following message:
and you have no clue about your password, do the following:
Delete the corresponding users keypair. It is located in
/opt/openvpn-als/adito/conf/repository/PKI/
For the user “test” this will be the following files:
/opt/openvpn-als/adito/conf/repository/PKI/test.pub /opt/openvpn-als/adito/conf/repository/PKI/test.prv
If you delete them, the user can logon again and will then be prompted for a new password for his private key (if “Confidential Mode” is set to “Prompt”). Of course, all previously saved attributes will be unreadable and you have to enter them again.
Managing extensions
Manually delete an uploaded extension
Of course you can delete an extension in the web-interface but if you need to delete an extension manually you can do it the following way:
Locate your extension on the server and delete the corresponding ZIP-File in the folder
/opt/openvpn-als/adito/conf/repository/archives/
After that, stop the server
service adito stop
and also delete the entry for your extension from
/opt/openvpn-als/adito/conf/prefs/system/extensions/prefs.properties
then restart the server
service adito start
Optional RADIUS authentication
If we want RADIUS support (as Authentication Scheme) on our server, we have to build the adito-community-radius authentication module. This is usually not needed for “normal” people, but larger companies often provide OTP (One Time Passwords) via RADIUS, so it might be useful to know how to set it up. If you don't use a RADIUS server, just skip this section!
cd /opt/openvpn-als/adito-community-radius ant install
The result should look like:
... install: [copy] Copying 1 file to /opt/openvpn-als/adito/conf/repository/archives BUILD SUCCESSFUL Total time: 3 seconds
For further information read:
more /opt/openvpn-als/adito-community-radius/README
You can now use RADIUS as Authentication Scheme.
- login as admin
- create a new authentication scheme and attach RADIUS module to it
- put the RADIUS-enabled authentication scheme to the top of the list (should you want that)
- edit RADIUS settings under “System Configuration → RADIUS” (and possibly restart)
The radius module Revision 703 from the Source Trunk already includes a fix that made it possible to login without password when the radius server did not respond! Do not use earlier versions. You can verify compare the code here: Comparison Revision 675 <-> 703
If you want to use Google-Authenticator via RADIUS look at this page!
Setup communication with RADIUS server
After installation of the module we have to setup the communication with the RADIUS server as shown in this sample:
Create RADIUS Authentication Scheme
Then we have to setup an authentication scheme for it. An example is shown in the following screenshots:
Now you can use RADIUS for User Authentication. Keep in mind, that the usernames have to be created with a hardcoded password. Just enable them with RADIUS then. You could disable other authentication schemes if you only would allow RADIUS authentication eg. using OTP-Tokens.
Links
OpenVPN ALS Windows Installer by Lars Werner
SSL Explorer 3SP Knowledge Base
Adito SSL Explorer install on Debian 5.0 Lenny 32 Bit
Building and installing Adito server
Zip with a lot of useful stuff
Create your own Extension Store (use save as and store locally)
OWA 2007 Reverse Proxy (use save as and store locally)
SSL Explorer Administrators Guide
Installing and Running the OpenVPN-ALS Server
Creating an extension that creates connection files