Enterprise Edition

Installation

Poseidon for UML Enterprise Edition has two components, the server and the client. The client is a complete modeling environment that can be used either stand-alone or in collaborative mode using a connection to the Enterprise Server, while the server contains everything needed to manage collaborations and projects and deploy changes to active project to all involved clients. However, we are using one single executable installer for both.

This section describes the installation process. For the server installation, the installation program should be executed under the user that will run the Enterprise Server later. The client installation must be run on each machine and for each user that will use this software. As the differences between the server and client installation are transparent to the user, only one description is given here.

Install the Client Application

The client software is installed via the installer program (PoseidonEE_<version>Installer). Depending on the local operating system, it can be started by double-clicking on its icon or calling the file from the command line. The installer will open a new window, presenting all the information needed during the installation process.

After clicking the 'Next' button, the License Agreement will be presented to you. You can either accept the agreement by clicking the 'I accept ...' button followed by the 'Next' button, or reject it by clicking the 'Cancel' button. Please read the agreement carefully before you decide which button to click. If you decide to reject the agreement, the installer will end without installing the software.

The 'Choose Alias Folder' screen allows you to decide where aliases for faster access to Poseidon should be created on your system. Although we recommend keeping the default settings, you can also choose other options or skip alias creation completely. Aliases for starting and uninstalling the software, the User Guide, and the FAQ will be created at the specified location.

A new screen will present a summary of the settings to be used, and the installer application will install Poseidon for UML Enterprise Edition to the default software installation folder for your operating system. By pressing 'Install' you confirm that the installation process should continue. The installer will start copying files to your system.

Once the installer has finished, you can start the Poseidon Enterprise Edition client application directly from the installer program (note that this will not start the server application) or exit the installer and manually start the client application.

Install the Server Application

Installing the Enterprise Server is very much the same. We recommend creating a new, dedicated user that will install and run the Enterprise Server. The user name and password of this user is needed for a correct setup at the client side. Therefore, using the account information of an existing, real user is considered insecure.

Licensing

Both the Enterprise Edition Server and the Enterprise Edition Client depend on a floating license server; therefore, you must have floating licenses for both products. These licenses need to be added to the floating license key pool by using the 'manageFloatingLicenses' tool. Without adding licenses to the available license pool, neither the Enterprise Edition Server nor the Client will start.

Licenses are added to the pool through a command-line interface: manageFloatingLicenses.{sh|bat} [register-serial] | [create-registration-data] | [add-final-key]

Options:

  • register-serial - Registers your serial number directly over the internet.

  • create-registration-data - Generates the registration data required for registering the serial number. Once you have generated the registration data, use the web form to receive your license key. The license key should then be added to the key repository using the 'add-license-key' option.

  • add-license-key - This task is needed to add a license key to your key repository.

Please keep in mind that you only can register you serial number one time. If you encounter problems with the registration process please visit: http://www.gentleware.com?redirect=contact

Configuration of the Network Environment

The Enterprise Edition features configurable ports used for the RMI connection between the Enterprise Server and its clients. If the Enterprise Edition is used only within a local network environment and none of the machines (server or any of the clients) are separated from each other through a firewall, the Enterprise Edition will work without any additional configuration. Should this be the case, you can skip the rest of this chapter.

Otherwise, a bit of configuration of the Enterprise Server and the affected firewall is needed. The Enterprise Edition uses different ports to allow communication between the server and the clients. Each collaboration will use its own port. In order to reduce the amount of ports that have to be opened in the firewall, the Enterprise Edition is able to restrict itself to use only a specific port range.

The ports used for communication between server and client can be configured using the property 'portrange' from the CollabServer.properties file. Only the starting port has to be specified here. The ports to be opened in the firewall will then be 7000 (RMI Activation Daemon), and portrange up to portrange + 21 will be used. For example, portrange = 9000 means 9000 – 9021 will be opened. The first port will be used for the RMI Naming Service, the second for the Enterprise Server, and the final twenty ports for any started collaborations. To increase the number of possible collaborations, increase the portrange.size property from the default 20 and be sure that these ports have been opened in the firewall.

First Start

This section details how to run the server and client for the first time.

Starting the Server

Before the Enterprise Server can be started for the first time, some adjustments must be made to the server properties. The properties can be found in the file poseidon2/EE/CollabServer.properties in the user’s home folder. The following entries are available (all of them starting with 'collabserver.'):

  • poseidon.ee.fl.server.port - Floating License Server port. The default is '6262'.

  • temp.file.location - Folder where temporary files are stored to by the Enterprise Server. This folder has to be accessible for the user running the server.

  • pool.size - Size of the License Pool.

  • cvs.encodedPassword - Location of the CVS password file

  • cvs.passFile - Location of the CVS password file.

  • project.file.location - Folder where project files are saved to and loaded from by the Enterprise Server. This folder has to be accessible for the user running the server.

  • queue.refresh.size - Number of events handled for one collaboration before the entrance of a new client to the collaboration forces temporary saving of the project. Use a smaller number than the default setting only if entering the collaboration late costs too much time or you have a slow network connection to the server.

  • server.debugLocking - Logs messages about the locking system behavior. For debug purposes only.

  • project.extension - File extension of the project files. Never change this value!

  • server.debugCommandExecution - Logs execution messages for each executed command. For debug purposes only.

  • poseidon.ee.fl.server - Location of the Floating License Server

  • server.debugCommandHandling - Logs messages about command transmission. For debug purposes only.

  • portrange - The starting port used for the RMI communication between server and clients. Only the starting port has to be specified. This port and the following 11 ones will then be used. If this property is not seAssociation Class: Association classes are imported, but not displayed correctly: They appear as simple associations. If you click on an association class, the Details pane displays the properties correctly, though.t, the default starting port will be 9000.

The Enterprise Server can be started from the command-line only. The script startCollaborationServer.[bat|sh] will bring up the core server component and the RMI infrastructure needed to run the Enterprise Server. Depending on the server settings, it is possible that a new background Poseidon instance is started automatically.

If starting Poseidon in the background fails with an exception coming from the RMI activation system, removing the log subfolder in the folder from which the start script is executed will solve this problem in most of the cases. The problem usually occurs only when the server machine changes its address (which can happen, particularly in DHCP-aware environments).

Make sure that the machine running the Enterprise Server has an SSH-Server running (e.g. sshd on Linux systems), otherwise starting collaboration based on existing project files will fail. Please see the following section for details about how to configure the SSH environment for the Enterprise Server.

If, for some reason, it becomes necessary to shut down the server, the script stopServer.[bat|sh] will execute this task. Any client connected to the Enterprise Server will receive a notification that the server is about to shut down. Active collaborations will be closed and their content will be saved to the corresponding project files. Additionally, the RMI activation system will be stopped.

Floating License Server

The Floating License Server is started with the Enterprise Edition Server. If you have valid floating licenses available, the start up should be no problem.

If you are using two or more Enterprise Edition Servers and only one floating license server, you will need to configure the location of the floating license server by editing your CollabServer.properties file located in the <poseidon2/EE> directory.

You must edit/add the following properties to change the search location of the Enterprise Edition Server:

  • collabserver.floating.server.host=<host>

  • collabserver.floating.server.port=<port normally: 6262>

Starting the Client

Once the installation is done, the client can be started either from the alias created during the installation process (e.g. on the desktop) or by using the start script (<installation folder>/bin/poseidon.[bat|sh]). For the EAP, a valid floating license that can be used for the local client is already included. See more details about the Floating License Server at the end of this chapter.

When starting the client for the first time, it is still configured for using the older, node-locked license scheme which is still part of the EAP for technical reasons. This static license is no longer good to work with collaborations. You have to switch to the floating license first. In order to do this, simply open the License Manager dialog (Help->License Manager) and select the floating license tab. Enter the address of the machine hosting the Floating License Server (same as the one hosting the Enterprise Server) and leave the port field unchanged. After pressing 'Apply', the configuration of the floating license mechanism is finished. The client will fetch a valid floating license automatically.

Before you can connect to the Enterprise Server, some additional settings must be entered. Open the settings dialog (Edit->Settings) and choose the 'Enterprise' tab. The 'Temporary File Directory' is used to store temporary files needed for the communication between your client and the Enterprise Server. Please set this value to a valid and existing folder. If the value is not set correctly, the Enterprise Edition will not work properly.

Ftp/ssh-username and ftp/ssh-password are used to establish a secure connection between the client application and the Enterprise Server. The username is the name of a user that has been created on the server machine and that has been configured to handle ssh-connections. The ftp/ssh-password is the password of that user. If you don’t know this information, ask your server administrator.

To change the password, press the 'Change Password' button. This will open up a new dialog asking you for the old password, a new password, and a retype of the new password (to avoid problems encountered through mis-typing). None of the password fields will show the password as plain text. If you are setting the password for the first time, the default value for the old password is 'password'. As using this password is considered insecure, change the password as soon as possible, even when you don’t intend to connect to the Enterprise Server immediately.

Press the 'Change Password' button in the password dialog to evaluate your input and return to the settings dialog. (Due to a known bug in window management, the settings dialog might be hidden in the background.) Press 'OK' in the settings dialog to apply the changes. Now you are ready to make your first connection to the Enterprise Server.

In order to start your first collaboration with the Enterprise Server, choose Enterprise->Connect to Server from the menu. In the field 'Username', enter a name the server can use to identify you. We recommend using your username, but any name is valid as long as it is unique to the server and does not contain whitespace.

From the combo box below, select the appropriate server. If this list is empty, add the new server to the combo box by clicking the 'Edit server-list' button and entering the server details. Servers are identified by their network identification, either the logical machine name or the IP address in dotted format. If you don’t know the address of your local server, ask your system administrator.

Once you have successfully connected to the Enterprise Server, the Collaboration-Management dialog will open. In the upper part, you will find a list of the currently active collaborations and their participants. You can choose to join one of them by selecting it from the list and pressing the 'Join selected collaboration' button. You can also start your own collaboration by pressing 'Create collaboration'. In the upcoming dialog you will be asked for the name of the new collaboration. Please make sure that the name is unique to the server and that it doesn’t contain whitespace.

In the lower part of the dialog, you will find a list of projects known to the Enterprise Server. You can start a collaboration based on one of these projects by selecting it and pressing 'Load and start selected project'.

The initialization of the collaboration might take some time, depending on the size of the collaboration. Once the initialization is finished, you are part of a live collaboration and can start sharing your modeling experience and ideas with others.

SSH Server

In order to allow file transfers between the Enterprise Server and the clients, an SSH server must be running on the server machine. Many systems (especially those running any kind of *NIX operating system) will already have an implementation of SSH installed. If the machine designated for the Enterprise Server has been used as workstation before, it is very likely that the SSH server isn’t started automatically

An SSH server must be running on the server machine - it is needed to encrypt commands and file-transfers between the server and the clients. It also allows for tunnelling of connections that would not make it through firewalls otherwise. Many systems (especially those running any kind of *NIX operating system) will already have an implementation of SSH installed. If the machine designated for the Enterprise Server has been used as workstation before, it is very likely that the SSH server isn’t started automatically.

For systems that do not have an SSH server installed, we provide an open-source implementation of the SSH protocol along with the Enterprise Edition EAP. See the next chapter for installation details. The implementation is based on OpenSSH and offers its own installation process through a self-extracting executable (see below). For Windows, a small Unix environment (reduced cygwin) is installed as well. If you are not sure if there is an existing SSH server installed (and running) on the server machine, ask your system administrator. It is also recommended to consult the system administrator before installing the OpenSSH package.

SSH Configuration

Once the SSH server is up and running on the server machine, some basic tweaking of the SSH environment has to be done. The following settings must be made (if you don’t know where to change the settings, asking your system administrator might be a good idea; for those want to do it on their own anyway, the configuration file is located in /etc/sshd-config or <openssh-installation-folder>/etc/sshd-config):

  • PasswordAuthentication yes

  • PasswordAuthentication yes

  • PermitEmptyPasswords no

  • RSAAuthentication no

  • Protocol 2,1

  • Port 22

Most of these settings are the default settings for the configuration. At the minimum, the RSAAuthentication must be set to 'no', otherwise clients will not be able to use project files from the server. If you make changes to the configuration, you will also have to restart the SSH server.

Installing the OpenSSh Server for Windows

If you are installing the OpenSSH server for Windows, please follow the instructions in the readme file to configure the server correctly. Note that you should not install OpenSSH over an existing installation of Cygwin, as it will possibly corrupt both installations.

Create the group and password files with the following commands from the \bin directory of the OpenSSH installation directory:

mkgroup -d >> ..\etc\group mkpasswd -d >> ..\etc\passwd

This makes the information about the users in your domain available for the OpenSSH server. If you want to use the local users of your windows system and not the domain users, please use the -l switch instead of the -d switch:

mkgroup -l >> ..\etc\group mkpasswd -l >> ..\etc\passwd

In this case, you have to configure your client with the correct username and password of the local user who is running the server. If you want to have a new local user who runs the server, please create this user before you execute the commands above.

Restart the OpenSSH server now.

Floating License Server

This release is delivered with a floating license server. The server is started and stopped using the same scripts as the Enterprise server. You must register your serial numbers and add the floating licenses to the pool before starting either the server or clients.

The floating license server is listening on port 6262. It is essential that no other process is using this port. You can change this port in the CollabServer.properties file.

To register a serial number:

  1. From the command line of your operating system, change directories to the installation directory of your Enterprise Edition.

  2. Use the manage floating licenses tool in the bin directory of your installation with the option register-serial to register your serial number and to receive a your license key.