Install the Service Manager Server

The Service Manager installer automatically copies AutoPass libraries as part of the server installation. AutoPass validates your license and determines what product features are enabled. Follow the steps in this section to obtain your permanent licenses.

1. Go to the Micro Focus Software Licensing website.

2. Log on to Micro Focus Passport.

3. Follow the instructions provided on the website to obtain license keys for your product.

4. Save the license key file to your system. Install license key(s) directly from a license key file. Do not manually transcribe and edit them from the activation certificate. Copy each license key file to the appropriate target system.

   As part of the process of obtaining a perpetual AutoPass license, a .dat file or several .dat files were sent to the email address that you provided. These files contain the licensing data required to use the applicable Service Manager modules. After you receive these files, follow these steps to move them to the Service Manager Server:

   1. Rename the .dat file to a .txt file so that you can open it with a text editor. For example, rename J8888X1624204.dat to J8888X1624204.txt.

   2. Create a text file named LicFile.txt and place it in the <Service Manager server installation path>/RUN/ directory.
   3. Copy the license data from the license .txt file that you created in step a and paste it in the LicFile.txt file that you created.

   Note Create the LicFile.txt file only once. If you request any additional licenses, append those licenses to the end of this file.

   Tip You can run the "sm -updatelicense" command to load a new license .txt file into the existing one.

   Note Make sure that the LicFile.txt file is not read-only. When you upgrade Service Manager from an earlier version, the first time when you start the Service Manager Server, the Server might need to change the content of the license file to the XML format if the AutoPass jar files were updated. If the license file is read-only, the Service Manager Server will fail to start.

5. If you plan to run your system in a horizontally-scaled environment, copy LicFile.txt to the <Service Manager server installation path>\RUN\ folder on all hosts running in the horizontal group. In addition, provide the grouplicenseip parameter for each host. The grouplicenseip value should match the IP address that you provided when obtaining the license key.

   Note If you have horizontal scaling implementation setup as a high availability failover cluster, you must request a permanent Service Manager license for both the virtual and the physical IP addresses of the host. Otherwise the Service Manager Server will fail to start.

Temporary licenses

You can use the following command line option to install a 90-day temporary license to evaluate, test, or develop your Service Manager system: sm -instantOn.

You can install a temporary license once per system. The license is valid for 60 days. Within this 60-day period, you must obtain a perpetual license key or a trial evaluation extension to continue using the product. During the last 10 days of the evaluation period, every user who logs in to the system will see a license expiration warning message. To remove the warning message, a system administrator must follow the steps above to obtain perpetual license files.

Next, make sure you meet the Service Manager server installation requirements.

Before you install the Service Manager Server, you should meet the following requirements.

For information about the supported operating systems and databases, refer to the Service Manager Support Matrix on the Micro Focus Support matrices web site.

Meet the requirements for a Windows system

1. Make sure that you have a compatible operating system with the current updates.

2. The Service Manager Server requires one of the following database resources.

   RDBMS	RDBMS server needed	RDBMS client needed
   Oracle	Oracle database	Oracle database client
   MS SQL	MS SQL Server	Windows ODBC DSN defined for SQL Server
   PostgreSQL	PostgreSQL Server	n/a

3. Have 1 GB RAM minimum. For production purposes, RAM is based on the expected user load.

   Note To avoid potential out-of-memory issues, we recommend that you run the ulimit -d unlimited command to set the heap size to unlimited before starting the Service Manager Server.

4. Create a local administrator account on the Windows server.
5. Have 1 GB of disk space.
6. Have a valid TCP/IP port that is greater than 1024.

7. Specify the appropriate number of processes. The system starts one process for each sm command line in the sm.cfg file. By default, each process is limited to 50 concurrent user sessions. The system assigns each user session or background process a dedicated thread.

   Note If you start background processes by using the sm system start command in the sm.cfg file, then the sm processes own the background process threads. If you start the background processes from a user session inside Service Manager, then the thread controller process that owns the user session also owns the background process threads.

8. Specify the amount of shared memory that you want the system to allocate. A server uses approximately 50 MB of base shared memory and requires an additional 5 MB of shared memory for every 50 users. You can specify the amount of shared memory the system allocates by using the shared_memory parameter in the sm.ini file.

9. For an Oracle database, update your system's PATH variable to include the path to the 32-bit versions of your RDBMS client. Refer to your operating system documentation for information on setting variables.

   For a Microsoft SQL Server database, configure ODBC DSN.

Meet the requirements for a Linux system

1. Make sure that you have a compatible operating system with the current updates.

2. The Service Manager Server requires one of the following database resources.

   RDBMS	RDBMS server needed	RDBMS client needed
   Oracle	Oracle database	Oracle database client
   PostgreSQL	PostgreSQL Server	n/a

3. Have 1 GB of disk space.
4. Have a valid TCP/IP port that is greater than 1024.

5. Specify the appropriate number of processes. The system starts one process for each sm command line in the sm.cfg file. By default, each process is limited to 50 concurrent user sessions. The system assigns each user session or background process a dedicated thread.

   Note If you start background processes by using the sm system start command in the sm.cfg file, then the sm processes own the background process threads. If you start the background processes from a user session inside Service Manager, then the thread controller process that owns the user session also owns the background process threads.

6. Create a separate user ID that owns Service Manager. Service Manager will not run from a root account. You only need root access to modify the system kernel, and mount the Service Manager DVD.
7. Run the installation script from an ANSI terminal to avoid rendering errors. Non-ANSI terminals such as hpterm may produce unreadable results.

8. Update your system's LD_LIBRARY_PATH variable to include the path to the 32-bit versions of your RDBMS client. Refer to your operating system documentation for information on setting variables.

9. Adjust kernel resources. A server uses approximately 50 MB of base shared memory and requires an additional 5 MB of shared memory for every 50 users. You can specify the amount of shared memory the system allocates by using the shared_memory parameter in the sm.ini file.

   The following kernel resource requirements are the minimum values required to run a Service Manager server. If you run other programs that require kernel resources on the same system as Service Manager, then add the Service Manager kernel resource requirements to the existing resources. For example, if the existing system requires 100 MB in kernel resources, and Service Manager requires an additional 50 MB, then update the kernel resources to 150 MB.

   To configure kernel IPC parameters:

   The default shared memory limit (both SHMMAX and SHMALL) is 32 MB, but you can change it from the proc file system without restarting the system. For example, to specify 128 MB:

   # echo 134217728 >/proc/sys/kernel/shmall
# echo 134217728 >/proc/sys/kernel/shmmax

   You can use sysctl.conf to control these parameters. Add the following to the /etc/sysctl.conf file:

   kernel.shmall = 134217728
kernel.shmmax = 134217728

   sysctl.conf is usually processed at startup but can be called later.

   • Modify the kernel parameters as needed:
     • shmmax: This parameter enables you to allocate shared memory. A server uses approximately 50 MB of base shared memory and requires an additional 5 MB of shared memory for every 50 users. Allocate more shared memory than what you specify in the sm.ini file.

     • shmmni: This kernel parameter enables you to set the maximum number of shared memory segments system-wide.

     Note Service Manager uses 12 semaphores, regardless of the number of users logged on to the system.

   • Make sure that the upper limit (ulimit -n size) for file descriptors is at least 1024.

   • Adjust the UDP buffer size to 20MB or higher. For better performance, if there is enough memory available on the server, choose a value larger than 20MB. Linux may generate warnings if the UDP buffer sizing set in the configuration files surpasses kernel limits. For example, a warning might look like the following:

     23966( 23966) 08/11/2009 15:38:33 receive buffer of socket java.net.DatagramSocket@c9d92c was set to 20MB, but the OS only allocated 131.07KB. This might lead to performance problems. Please set your max receive buffer in the OS correctly (e.g. net.core.rmem_max on Linux)

     A superuser can change 0 kernel limits to enhance performance of UDP communication. To retrieve the UDP buffer sizing setting, use the sysctl -w net.core.rmem_max command. To change the setting, use the sysctl -w net.core.rmem_max=8388608 command.

10. Make sure that the user running the installation script has permission to create new directories in the chosen installation path.

11. For 64-bit Linux, install the required libraries to support 32-bit Java on a 64-bit system by running the following command as “root”:

    Tip This step is required only when you are using an Oracle jre.

    yum -y install glibc.i686

    You may need to update /etc/yum.repos.d with the working links for the required package if necessary.

    Caution If the required 32-bit libraries are missing from the system, an “Unsupported java version” error will occur later when you configure or start the server by running the configure or smstart script. As a result, you will not be able to configure or start the server.

Next, install and configure the Service Manager Server.

To install the Service Manager Server on a Windows system, complete the following tasks.

Task 1: Install the Service Manager 9.60 Server

To install the Service Manager Server, follow these steps:

1. Log on to the Windows server as a user with local administrator privileges.
2. Extract the server package file into the appropriate drive of the server.
3. Navigate to the Installation\Server folder, and double-click setupserver-9.60.exe.
   
4. Click Next to read and accept the licensing agreement.
5. Select the I accept the terms of the License Agreement option. The Next button becomes active.

6. Click Next to accept the default installation folder: C:\Program Files (x86)\Micro Focus\Service Manager 9.60\Server, or click Choose to choose a different installation location.

   Caution Do not install the server over existing versions of Service Manager. Install in a new folder. The Service Manager server folder name cannot contain parentheses or use non-ASCII characters. The server cannot start if installed in a folder with a non-compliant folder name.

   Note If you have two different versions of the Service Manager Server (for example, the 9.21 server and 9.60 server) installed on the same server host, you will not be able to start both of them at the same time - your attempt to start the second server will fail with an error in the server log that indicates the program that created the shared memory is incompatible with the current program. This is because the two servers are different binaries, which cannot be attached to the same shared memory.

7. Click Next to prepare the installation process. The summary information page opens.
8. Click Install to copy the installation files.
9. When the installation is complete, click Next.

10. Select the Run the Server Configuration Utility after installation option to open the configure server tool at the end of the installation.

    Note You can skip this step and configure the Service Manager server manually by editing the RUN\sm.ini initialization file in a text editor.

11. Click Done to exit the installation wizard. The server installation is complete, and the Configuring Service Manager Server wizard opens. Follow the steps in the next section to configure the server.

Task 2: Configure the Service Manager 9.60 Server

You can customize your server installation by modifying the Service Manager initialization file (sm.ini).

When you install the server for the first time, the default settings are configured for the sample database. While this tool is intended to configure new or test implementations running the out-of-box sample data, you can use it whenever you want to change the settings in your system’s sm.ini file. Refer to the Service Manager Help for a complete list of the parameters stored in the sm.ini file.

To configure the Service Manager server, follow these steps:

1. Run the Server Configuration Utility, configure.bat, located in the <Service Manager installation path>\Server directory.
   1. Specify the listener ports:
      • HTTP Port (system): The communications port on which you want Service Manager to listen to client connection requests. The default port is 13080.

      Note For a new server installation, the configuration wizard does not display the Enable HTTPS Port and HTTPS Port options, because SSL is not enabled by default (the sm.ini file contains the sslconnector:0 parameter). If you have already set sslconnector:1 in the sm.ini file and then rerun the configuration utility, the configuration wizard displays two HTTPS options so that you can reconfigure the HTTPS settings:

      • Enable HTTPS Port: Select this option to enable an HTTPS port.
      • HTTPS Port: The communication port on which you want Service Manager to listen to secure client connection requests.
   2. Specify the database type and connection information:
      • Database Type: The database that you want to use to store your data.

      • SQL Database Name:

        For Microsoft SQL Server, this is the ODBC DSN name. Note that Microsoft SQL Server is supported for a Windows platform only.

        For Oracle Database, this is the Network Service Name in tnsnames.ora.

        For PostgreSQL Database, this includes database host, port, and database name. The format is as follows: host=<db_server_host> port=<db_port> dbname=<db_name>

      • SQL User: The user that Service Manager should connect to your database with.
      • SQL Password: The password for the user that Service Manager should use to connect to your database.

      • Use Unicode Data Type: Use this option if you need to support multiple languages that are not supported by one collation. Otherwise, use the right collation and do not select this option. For information about how to select SQL Server collations, refer to the SQL Server documentation.

        Caution Be aware that this operation is not reversible.

      • PG Schema: Specify the schema created for the Service Manager database. If you leave it empty, the default "public" schema is used, which is not recommended. This option is for PostgreSQL only.
      • Case Insensitive: By default, Service Manager does not support case-insensitive searching when using PostgreSQL. Select this option if you want to use case-insensitive searching. Because this option is set when initializing the database, if you need to change this option, you must load the SM data again after the change. This option is for PostgreSQL only.
   3. Click Verify Connection to confirm that Service Manager can connect to the database.

   4. Upload the SM demonstration data, if desired. All new Service Manager installations require this. Uploading the demonstration data also uploads the out-of-box 9.60 applications. If you are upgrading only the Service Manager client and server, you do not have to upload the data. The new client and server can connect to your old system.

      Note Before your system goes live, you need to purge the out-of-box demonstration data by running the PurgeOutofBoxData unload script. For details, see knowledge article KM718390.

      Caution  Do NOT upload the data into an existing production system. Instead, you need to perform an applications upgrade. For more information, see Service Manager Applications Upgrade .

      Note If you selected the Unicode data type for SQL Server, the applications and demonstration data are uploaded as Unicode. Additionally, to indicate that your SQL Server database uses Unicode, the read-only Use Unicode Data Type flag is turned on in the sqlserver record of the sqldbinfo table.

2. In a text editor, open the sm.ini file and add the following parameters:

   • jsaccessfilereadregex
   • jsaccessfilewriteregex
   • jsaccesscmdregex

   Important These parameters specify access restrictions from JavaScript code for file access and command execution. Configuration of these parameters is required so that users with Process Designer tailoring rights are not able to use the available Service Manager JavaScript APIs to directly access the underlying host file system and command line.

   For more information about how to configure these parameters, see Startup parameters: JavaScript access.

To install the Service Manager Server on a Linux system, complete the following tasks.

Task 1: Install the Service Manager9.60 Server

To install the Service Manager Server, follow these steps:

1. Log on to the Linux server as a user with local administrator privileges.
2. Extract the server package file into the appropriate drive of the server.
3. Navigate to Installation/Server directory.

4. Run the setupLinuxX64-9.60.bin script.

   Note The setup scripts assume you will run them from an X-Windows environment. If you prefer to run the scripts from a console instead, add “-i console” to the command line. For example, setupLinuxX64-9.60.bin –i console.

5. Accept the license agreement.

6. At the installation script prompt, type the absolute installation directory where you want to install Service Manager, or accept the default one. Follow these rules:

   • Do not install the server over an existing version of ServiceCenter or Service Manager. Install in a new folder.

     Note If you have two different versions of the Service Manager Server (for example, the 9.21 server and 9.60 server) installed on the same server host, you will not be able to start both of them at the same time - your attempt to start the second server will fail with an error in the server log that indicates the program that created the shared memory is incompatible with the current program. This is because the two server versions are different binaries, which cannot be attached to the same shared memory.

   • The installer will ask you to confirm if the specified installation directory is correct. If you specify an invalid directory, the installer behaves unexpectedly.

   • Do not use the "~" symbol when entering the path. InstallShield treats this as a regular character, and will create a directory with the name '~'.

   The system takes several minutes to uncompress the files and complete the server installation.

7. Click Finish to exit the wizard.

8. If you want to use an OpenJDK JRE, make sure your Linux host has Internet access and then run one of the following commands as a superuser (such as root) in the Server installation directory:

   • For Red Hat Linux or Oracle Linux: run the "installOpenJDK.sh -i4sm" command.
   • For SUSE Linux: run the "installOpenJDKSUSE.sh -i4sm" command.

   If you want to use an Oracle JRE, do the following:

   1. Update the JAVA_HOME environment variable to make it point to the Oracle jre.
   2. From the Server's RUN directory, run the "setupLinks.sh jre" command as the owner of the Service Manager installation directory. This will create a symbolic link for the Oracle jre.

   For more information, see the JRE support section in Deployment architecture.

9. To automatically configure the server, run the configure script in your <Service Manager Server installation path> directory to update the sm.ini file.

   Note You can also configure the Service Manager server by editing the sm.ini configuration file. Follow the instructions in the next task if you want to configure the server manually.

Task 2: Configure the Service Manager9.60 Server

You can customize your server installation by modifying the Service Manager initialization file (sm.ini).

When you install the server for the first time, the default settings are configured for the sample database. While this tool is intended to configure new or test implementations running the out-of-box sample data, you can use it whenever you want to change the settings in your system’s sm.ini file. Refer to the Service Manager Help for a complete list of the parameters stored in the sm.ini file.

To configure the Service Manager server, follow these steps:

1. From a console, run the server configuration script, configure, located in the <Service Manager installation path>/Server directory:

   configure -consolemode

   1. Specify the listener ports:
      • HTTP Port (system): The communications port on which you want Service Manager to listen to client connection requests. The default port is 13080.
      • Enable HTTPS Port: Select this option to enable an HTTPS port.
      • HTTPS Port: The communication port on which you want Service Manager to listen to secure client connection requests.

      Note For a new server installation, the configuration wizard does not display the Enable HTTPS Port and HTTPS Port options, because SSL is not enabled by default (the sm.ini file contains the sslconnector:0 parameter). If you have already set sslconnector:1 in the sm.ini file and then rerun the configuration utility, the configuration wizard displays these two HTTPS options so that you can reconfigure the HTTPS settings.

   2. Specify the database type and connection information:
      • Database Type: The database that you want to use to store your data.

      • SQL Database Name:

        For Oracle Database, this is the Network Service Name in tnsnames.ora.

        For PostgreSQL Database, this includes database host, port, and database name. The format is as follows: host=<db_server_host> port=<db_port> dbname=<db_name>

      • SQL User: The user that Service Manager should connect to your database with.
      • SQL Password: The password for the user that Service Manager should use to connect to your database.
      • PG Schema: The schema created for the Service Manager database. If you leave it empty, the default "public" schema is used, which is not recommended. This option is for PostgreSQL only.
      • Case Insensitive: By default, Service Manager does not support case-insensitive searching when using PostgreSQL. Enable this option if you want to use case-insensitive searching. Because this option is set when initializing the database, if you need to change this option, you must load the SM data again after the change. This option is for PostgreSQL only.

   3. Verify the connection to confirm that Service Manager can connect to the database by running the command sm -sqlverifyconnection in the Service Manager RUN directory.

   4. Upload the SM demonstration data, if desired. All new Service Manager installations require this. Uploading the demonstration data also uploads the out-of-box 9.60 applications. If you are upgrading only the Service Manager client and server, you do not have to upload the data. The new client and server can connect to your old system.

      Note Before your system goes live, you need to purge the out-of-box demonstration data by running the PurgeOutofBoxData unload script. For details, see knowledge article KM718390.

      Caution  Do NOT upload the data into an existing production system. Instead, you need to perform an applications upgrade. For more information, see Upgrade Service Manager.

2. In a text editor, open the sm.ini file and add the following parameters:

   • jsaccessfilereadregex
   • jsaccessfilewriteregex
   • jsaccesscmdregex

   Important These parameters specify access restrictions from JavaScript code for file access and command execution. Configuration of these parameters is required so that users with Process Designer tailoring rights are not able to use the available Service Manager JavaScript APIs to directly access the underlying host file system and command line.

   For more information about how to configure these parameters, see Startup parameters: JavaScript access.

1. Stop the Service Manager server.

2. Run the following commands to uninstall the server:

   cd <install path>/ServiceManager9.60/_uninstall

   uninstaller –i console

3. Delete all of the Service Manager server directories and subdirectories.