Installing the application server on Linux

Before you begin

Before you install the application server, perform the following tasks:

• Ensure that you have performed all of the prerequisite steps in Setting up for installation on a Linux server.
• The TrueSight Network Automation installer cannot create a user account on a server running Ubuntu 11. Create the user account before starting the installation program. For information about creating a user account, see (Optional) Creating a user account on a Linux server.
• If you plan to use SAML 2.0 as the authentication mechanism, you must register the host on which you want to install TrueSight Network Automation with the Identity Provider (IdP). While registering, you need to provide the TrueSight Network Automation URL in the following format: https://hostName:portNumber/bca-networks/api/saml.
  hostName indicates the name of the computer where you want to install TrueSight Network Automation. 
  portNumber indicates the port number for https communication.
  For more information about SAML 2.0 authentication, see Authentication.
• If you have installed any intrusion prevention system, such as McAfee Intrusion Protection, ensure that it is disabled before you start the installation process. You can enable it once the installation is complete.
  

To install the application server

1. Log on as root to the host computer where you want to install the application server.  
2. Run the umask 022 command.
3. Locate the file that you downloaded from the BMC EPD site or on media if you purchased the product with media.
   For information about the EPD site, see Downloading-the-installation-files.
   On media, the Linux installation files are in the /install/linux subdirectory.
   For either downloads from EPD or media, the file name is: tsna-server-v.r.mm-linux64.tar.gz

4.  Extract the file by using the following command. The -p option is required: 
   tar -pzxvf tsna-server-v.r.mm-linux64.tar.gz

   Important

   In case of application server or remote device agent upgrade, ensure that you do not extract the tar file into the existing Disk1 directory. Either extract into a new directory or delete the existing Disk1 directory before extracting the tar file.

   The following table lists the files contained in the download:

   File	Description
   Disk1/setup.sh	The main installation executable
   Disk1/setup.jar	Compressed Java archive that contains installation files
   Disk1/files, Disk1/bc-fips-1.0.1.jar	Main installation files
   Disk1/utility/BcanMaintenanceTool.sh	Installation maintenance utility used for various tasks. See Running-the-Maintenance-and-Cleanup-tools.

5. Run the following command to start the installation program: 
   ./setup.sh
   The installer might take a minute or more to start.
6. Welcome panel: Click Next.
7. End User License Agreement panel: Review the TrueSight Network Automation Software License. Select I agree to the terms of the license agreement to continue the installation, and then click Next.

8. Component Selection panel: Select the Server with Local Device Agent option.

   Important

   The wizard prevents the installation of the server if it detects that a remote device agent has previously been installed on this computer.

9. Installation Type Selection panel: Select the (default) Typical Setup or Custom Setup option, and click Next.
   Use the following table to select the appropriate option:

    Linux typical versus custom installation

10. Installation Directory panel: Specify the directory in which you want to install the product in the Destination Directory field, and click Next. This directory is the BCAN_HOME directory. (Default) /opt/bmc/bca-networks

    Important

    • Do not use any spaces, pound ($), hash (#), or at sign (@) in the directory path.
    • The directory path cannot contain any non-Latin characters (Chinese, Japanese, Korean, or similar). These characters cause the installation to fail.
    • You must install the software on a local drive. Do not install the software on a network drive.
    • BMC recommends using the default value for continuity with uninstallation and future upgrades.

11. Data Directory Information panel: Specify the directory in which you want to install the product data files in the Data Directory field, and click Next. This directory is the BCAN_DATA directory. (Default) /var/bca-networks-data
    

    Notes

    • Do not use any spaces, or the pound ($), hash (#), or at (@) sign in the directory path.
    • The directory path cannot contain any non-Latin characters (Chinese, Japanese, Korean, or similar). These characters cause the installation to fail.
    • Do not use the root directory.
    • BMC recommends using the default value for continuity with uninstallation and future upgrades.
    • You must install the data files on a local drive. Do not install the data files on a network drive.
    • Ensure that the database directory contains at least 3 GB of free space per 1000 devices because the operational data would increase in size.

12. OS User Account Information panel: Enter the user name, password, and user group of the BCAN_USER account if this account was created before installation, and click Next.
    If this account was not created, select Create User Account and enter the required information. After the installation, assign the required permissions to this account as mentioned in (Optional) Creating a user account on a Linux server.

    The installer confirms the user name and password during installation. If the user name, password, or group is incorrect, an error message gives details of the problem. Click Previous and enter the correct information.
    
    

    Important

    For security purposes, the enatomcat service starts with the user account that you provide in this step. By default, the installer restricts only the users that are part of the root group. Therefore, BMC recommends that you provide details of a non-privileged user account.

13. Web Server Information panel: Change the Web server port numbers, as necessary, to avoid conflicts with other applications on the same host computer, and click Next.
14. (This step is applicable only if you plan to have multiple application servers in your environment and you plan to transfer the content containing sensitive data (for example, Device Security Profiles) across these application servers. Transfer refers to importing and exporting content using the UI or utility, pushing content using TrueSight Network Automation - Multi-Server Administration, or use of Web Services and REST APIs.) Do the following during installation of the second application server:
    1. Log on to the computer where you want to install a subsequent instance of application server.
    2. Create a directory named bca-networks-data in the path you specified in step 11. For example, if you have specified var/bca-networks-data as the path in step 11, create the directory in the /var directory.
    3. Log on to computer where you have installed the first instance of  Network Automation.
    4. Navigate to the bca-networks-data directory and copy the keystore.jceks file.
    5. On the other computer, go to the bca-networks-data directory and paste the keystore.jceks file.

15. Certificate Information panel: Enter all of the information required for the HTTPS certificate, and click Next.

    Important

    Starting with version 8.7.00, the product uses the SHA256WithRSA encryption algorithm to generate a self-signed certificate. By default, the size (in bits) for the certificate key is set to 4096. However, you can also generate and import a third-party SSL certificate into TrueSight Network Automation.

16. (Optional) Database Information Validation error panel: This panel appears if you are using the GNU C Library version earlier than 2.12. Upgrade to version 2.12 or later if you want to use the PostgreSQL (Embedded) database, and then click Next.

    Use the ldd --version command to display the current version of the library.

17. (Custom installation) Database Information panel: Select and configure the database that you want to use with Network Automation, and click Next.
    PostgreSQL (Embedded) is the default database. This embedded database is installed, upgraded and maintained as part of the product. You can change its defaults if you want.

    Important

    Before you perform this step, review Database-requirements.

    The following table lists all the options for the various databases. The three columns on the right indicate which database types have these options.
    
    Database options 

    Important

    To set up Oracle RAC, select Advanced Connection Settings, and then enter a string similar to the following examples:
    
    Single Node Environment:
    (DESCRIPTION = (ADDRESS = (PROTOCOL=TCP)(HOST= 10.128.251.110)
    (PORT=1521))(LOAD_BALANCE = yes)(CONNECT_DATA = (SERVER = DEDICATED)
    (SERVICE_NAME = orcl1)(FAILOVER_MODE = (TYPE = SELECT)(METHOD = BASIC))))
    
    Cluster Environment:
    (DESCRIPTION=(FAILOVER=ON)(ADDRESS=(PROTOCOL=TCP)
    (HOST=scaserv12-orac-1-vip.sca1.bladelogic.com)(PORT=1521))
    (ADDRESS=(PROTOCOL=TCP)(HOST=scaserv12-orac-2-vip.sca1.bladelogic.com)
    (PORT=1521))(LOAD_BALANCE=yes)(CONNECT_DATA=(SERVICE_NAME=BL)))
    
    Cluster Environment with SCAN name for Oracle 11g R2 and later:
    (DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)
    (HOST=bna-oracle-scan-859192.domain.com)(PORT=1521))
    (CONNECT_DATA=(SERVICE_DEDICATED)
    (SERVICE_NAME=orcl.domain.com)))

18. (Custom installation and Create New User is selected in the previous step) Database Administrator User Inputs panel: Enter the information listed in the following table and click Next:

19. (Custom installation) Authentication Source panel: Select either Local, Active Directory, LDAP, RADIUS, TACACS/TACACS+, SAML 2.0, or RSSO as the authentication method that you want to use for the TrueSight Network Automation user and click Next.
    When local authentication is selected (default), the product maintains the user account password. Additional configuration panels are displayed based on the authentication method you select.

    Tip

    If you cannot log on using external authentication after installing the software, see Troubleshooting-user-login-to-external-authentication.

    1. 1. (Active Directory) Active Directory Connection Information panel: Enter the following connection settings and click Next.
          
          

       2. Active Directory Search Filter Information panel: Define the Active Directory user account search criteria, and click Next:

       3. (Optional) After installation, if the authentication fails (for example, users cannot log on), you can manually tweak the settings in the server.xml and/or catalina.properties files located in the BCAN_HOME/tomcat/conf directory. The following code snippet shows an excerpt of an example server.xml file that references an Active Directory authentication setup:

          Example

          <!-- BEGIN: BCA-Networks realm configured by InstallShield -->
           <Realm className="org.apache.catalina.realm.JNDIRealm"
                  connectionURL="${bna.jndiRealm.connectionURL}"
                  connectionName="${bna.jndiRealm.principal},${bna.jndiRealm.baseDN}"
                  connectionPassword="${bna.jndiRealm.connectionPassword}"
                  userBase="${bna.jndiRealm.userBase}${bna.jndiRealm.baseDN}"
                  userSearch="${bna.jndiRealm.userSearch}"
                  userSubtree="${bna.jndiRealm.userSubtree}"
                  referrals="${bna.jndiRealm.referrals}"/>
          <!-- END: BCA-Networks realm configured by InstallShield -->

          
          

          The following code snippet shows an excerpt of an example catalina.properties file that references an Active Directory authentication setup:

          bna.jndiRealm.connectionURL=ldap://ad.lab.local:389
          bna.jndiRealm.alternateURL=
          bna.jndiRealm.principal=cn=Administrator,ou=Service Accounts
          bna.jndiRealm.baseDN=dc=bmc,dc=com
          bna.jndiRealm.connectionPassword=ddc915f58d57996a8fd9e65cb6d76c40
          bna.jndiRealm.userSearch=(sAMAccountName={0})
          bna.jndiRealm.userBase=ou=Service Accounts,
          bna.jndiRealm.userSubtree=true
          bna.jndiRealm.referrals=follow

       4. (Optional) If you modify the server.xml and/or catalina.properties files manually, stop and start the BCA-Networks Web Service. See Managing-product-services for instructions on how to stop and start the BCA-Networks Web Service.

          Important

          Changes to server.xml are lost during a subsequent upgrade (the file is overwritten). Changes to catalina.properties are preserved.

       5. Proceed to step 20.

       6. (LDAP) LDAP Connection Information panel: Enter the following connection parameters and click Next:

       7. LDAP Search Filter Information panel: Define the LDAP user account search criteria, and click Next:

       8. (Optional) After installation, if the LDAP authentication fails (for example, users cannot log on), you can manually tweak the settings in the server.xml and/or catalina.properties files located in the BCAN_HOME/tomcat/conf directory. The following code snippet shows an excerpt of an example server.xml file that references an LDAP authentication setup:

          Example

          <!-- BEGIN: BCA-Networks realm configured by InstallShield -->
           <Realm className="org.apache.catalina.realm.JNDIRealm"
                  connectionURL="${bna.jndiRealm.connectionURL}"
                  connectionName="${bna.jndiRealm.principal},${bna.jndiRealm.baseDN}"
                  connectionPassword="${bna.jndiRealm.connectionPassword}"
                  userBase="${bna.jndiRealm.userBase}${bna.jndiRealm.baseDN}"
                  userSearch="${bna.jndiRealm.userSearch}"
                  userSubtree="${bna.jndiRealm.userSubtree}"
                  referrals="${bna.jndiRealm.referrals}"/>
          <!-- END: BCA-Networks realm configured by InstallShield -->

           The following code snippet shows an excerpt of an example catalina.properties file that references an LDAP authentication setup:

          bna.jndiRealm.connectionURL=ldap://ldap-server:389
          bna.jndiRealm.alternateURL=ldap://backup-ldap-server:389
          bna.jndiRealm.principal=cn=bmcsadmin,ou=Service Accounts
          bna.jndiRealm.baseDN=dc=bmc,dc=com
          bna.jndiRealm.connectionPassword=ddc915f58d57996a8fd9e65cb6d76c40
          bna.jndiRealm.userSearch=(uid=\{0\})
          bna.jndiRealm.userBase=ou=Users,
          bna.jndiRealm.userSubtree=true
          bna.jndiRealm.referrals=follow

       9. (Optional) If you modify server.xml and/or catalina.properties manually, stop and start the BCA-Networks Web Service. See Managing-product-services for instructions on how to stop and start the BCA-Networks Web Service.

          Important

          Changes to server.xml are lost during a subsequent upgrade (the file is overwritten). Changes to catalina.properties are preserved.

       10. Proceed to step 20.

       11. (RADIUS) RADIUS Connection Information panel: Enter the following connection parameters and click Next.

           The [confluence_table-plus] macro is a standalone macro and it cannot be used inline. Click on this message for details.
           This macro generates standalone content. As a consequence you need to make sure to use a syntax that separates your macro from the content before and after it so that it's on a line by itself. For example in XWiki Syntax 2.0+ this means having 2 newline characters (a.k.a line breaks) separating your macro from the content before and after it.
           The host name or names that you enter must be known host names in the environment where you are installing the software (that is, must be resolvable).
           If the RADIUS server host name cannot be resolved, if the shared secret does not match the one at the server, or if the server does not support the selected authentication type, any logon attempt fails with an invalid user name or password error message.
           The BCA-Networks.log.0 file provides more detail as to the cause; the server might also have logs that provide information about the failed logons. If any of the parameters are entered incorrectly at installation time, you must re-run the installer and enter the correct values.
           The default location for the BCA-Networks.log.0 file is /var/bca-networks-data/log.

       12. Proceed to step 20.

       13. (TACACS/TACACS+) TACACS Connection Information panel: Enter the following connection parameters and click Next:

           Important

           When using TACACS for authentication and Cisco ACS as the authentication server, if Cisco ACS is set up to forward requests to a higher-level database for domain accounts, you must use PAP as the authentication mode. Other modes result in local accounts passing but domain account failing authentication.

           If there is a problem reaching the server, if the shared secret does not match the one at the server, or if the server does not support the selected authentication type, any logon attempt fails with an invalid user name or password error message.
           The BCA-Networks.log.0 file provides more detail as to the cause; the server might also have logs that provide information about the failed logins. If any of the parameters are entered incorrectly at installation time, you must re-run the installer and enter the correct values.
           The default location for the BCA-Networks.log.0 file is /var/bca-networks-data/log.

       14.  SAML 2.0 Connection Information panel: Enter the following connection parameters and click Next:

       15. RSSO Server: Enter the following information:

           Setting	Description
           RSSO Server URL	Enter the RSSO server details to which Network Automation will be redirected for authentication. The URL must be in the following format: https://<rsso-server>.<rsso-cookie-domain>/rsso
           Administrator Username	Enter the username of the account which acts as the Network Automation Administrator. If you do not specify a valid username, you cannot log on to configure Network Automation. The username does not necessarily have to correspond with the administrator of the external authentication server.

       16. Proceed to step 20.

20. Memory and System Options panel: Change memory settings or enter additional startup options if required, and click Next.

    The [confluence_table-plus] macro is a standalone macro and it cannot be used inline. Click on this message for details.
    This macro generates standalone content. As a consequence you need to make sure to use a syntax that separates your macro from the content before and after it so that it's on a line by itself. For example in XWiki Syntax 2.0+ this means having 2 newline characters (a.k.a line breaks) separating your macro from the content before and after it.The [confluence_table-plus] macro is a standalone macro and it cannot be used inline. Click on this message for details.
    This macro generates standalone content. As a consequence you need to make sure to use a syntax that separates your macro from the content before and after it so that it's on a line by itself. For example in XWiki Syntax 2.0+ this means having 2 newline characters (a.k.a line breaks) separating your macro from the content before and after it.

21. Installation Preview panel: Review the summary information, and then click Install.
    If you need to change a setting, click Previous. Each panel retains previous entries unless you change them.
    A panel appears indicating that the installation completed successfully. As part of a successful server installation, the product installs startup scripts into the /etc/systemd/system directory:

    • /etc/systemd/system/enapostgres.service (database server)
    • /etc/systemd/system/enatomcat.service  (web server)
      
      

    Important

    For security purposes, the enatomcat service starts with the user account that you provide in step 12. By default, the installer restricts only the users that are part of the root group. Therefore, BMC recommends that you provide details of a non-privileged user account.

22. Finish and log file panel: Review the summary information. To view the installation log file click View Log. Otherwise click Next.
    The name of the log file is bcan_install_log.txt. The location of the file is /tmp.
23. On the final page, click Done.

Deleting the embedded PostgreSQL password file

The embedded PostgreSQL password is stored in the pgpass.conf file located in the BCAN_HOME/tools directory. This is a protected file and stored in this location to allow for easier execution of the embedded PostgreSQL scripts (init_db.sh, query_db.sh, and so forth). When this file is present, the scripts do not prompt for a user name or password.

If security of the filesystem is a concern, then this file can be safely removed after the installation. In this case, the database scripts prompt for password information.

Troubleshooting installation issues

Any warnings related to illegal reflective access operation in the log file can be safely ignored and need not be reported to BMC Customer Support. For more information, see Warnings-in-logs. 

If you face any other issue during installation, see Troubleshooting-the-installation-migration-or-upgrade.

Where to go next

• If you need to install remote device agents, see Installing-the-remote-device-agent-on-Linux.
• If you want to install additional components on your Linux server, see Installing-optional-components-on-Linux.

• If you are finished with the installation, log on to the application server using the user accounts mentioned in Accessing-the-interface and then go to Configuring-after-installation.

  Important

  If you want to set up your TrueSight Network Automation system in a stand-alone configuration, see Performing-a-quick-start-configuration.