In the Xconf RDK community instance , the data service and Admin UI is added standalone jetty services and both are deployed in the same VM. This documentation explains the steps that were followed to achieve it.

KeyPoints

• According to this tutorial, Cassandra DB and the two xconf applications are deployed in the same server
• The xconf applications – data service and admin ui are deployed in two separate jetty instances
• In usual cases the applications will be deployed in seperate nodes, Eventhough the document is based on our experience in setting up both the services in a single server, this document can be referred for  how the application can be deployed in jetty as a system service and also how ssl can be enabled in a jetty server with CA provided certificates

Prerequisites 

• Required: Xconf dataservice and Xconf admin ui war files
• Environment: Ubuntu 18.04
• OpenSSL (Open SSL has to be installed and added to PATH)
• Jetty 9.4.37
• Install Java
• Setup Cassandra DB

Deploy Xconf-data-service war

• Create folder ‘jetty’ and install jetty in it by downloading jetty 9.4.37 version using ‘wget’ command. In this case, JETTY_HOME directory is /opt/jetty

           cd /opt
           mkdir jetty
           cd jetty
           wget https://repo1.maven.org/maven2/org/eclipse/jetty/jetty-distribution/9.4.37.v20210219/jetty-distribution-9.4.37.v20210219.tar.gz
           gzip –d jetty-distribution-9.4.37.v20210219.tar.gz
           tar -xf  jetty-distribution-9.4.37.v20210219.tar.gz--strip=1

• Copy war file to webapps folder and make it to ROOT.war. This is to
  get the application URL in the format “http://127.0.0.1:9092/queries/environments”

          To rename – sudo mv xconf-dataservice.war ROOT.war

• Copy the service.properties file to JETTY_HOME directory
  
  
• Edit start.ini in your JETTY_HOME directory with the following contents. 

         --module=https
         etc/jetty-ssl.xml
        -DappConfig=service.properties
        -Djetty.logs=/opt/jetty/logs

• Follow the steps mentioned in the session 'Https using CA certificate in jetty for enabling SSL'
• Go to JETTY_HOME
• Copy jetty.sh to init.d
  

  cp bin/jetty.sh /etc/init.d/jetty

• Create the file /etc/default/jetty with the following data
  

  vim /etc/default/jetty
  JETTY_HOME=/opt/jetty

  Before starting jetty as a service we can verify if the app is running by stepping into {jetty-home}/ and run the command java –jar start.jar –DappConfig=service.properties

• To run the jetty service
  

  sudo service jetty start

• To check the status

     sudo service jetty status

• If jetty run is not successful, then run this command
  update-rc.d <service> defaults (update-rc.d jetty defaults)

Deploy Xconf Admin Service

• Create folder ‘jetty2’ and install jetty in it 

      cd /opt
      mkdir jetty2
      cd jetty2
      wget https://repo1.maven.org/maven2/org/eclipse/jetty/jetty-distribution/9.4.37.v20210219/jetty-distribution-9.4.37.v20210219.tar.gz /copy the tarball file from /opt/jetty
      gzip –d jetty-distribution-9.4.37.v20210219.tar.gz
      tar -xf  jetty-distribution-9.4.37.v20210219.tar.gz--strip=1

(Or copy the jetty tar ball file from data service setup)

• Copy war file to webapps folder and rename it to admin.war

                mv xconfAdminService2.war admin.war

• Copy the service.properties file to jetty home (/opt/jetty2) folder.
• Edit start.ini with the following contents. (If we want to enable both http and https)

        --module=https
        jetty.http.port=9093
        etc/jetty-ssl.xml
        -DappConfig=service.properties

• Follow the steps mentioned in the session 'Https using CA certificate in jetty for enabling SSL' for this jetty instance
• Copy jetty.sh to init.d

  cp bin/jetty.sh /etc/init.d/jetty2

• Create the file /etc/default/jetty2 with the following data

  vim /etc/default/jetty2
  JETTY_HOME=/opt/jetty2             

  Before starting jetty as a service we can verify if the app is running by stepping opt/jetty2 and run the command java –jar start.jar –DappConfig=service.properties

• To run jetty as service
  

  sudo service jetty2 start

• To check the status 
  

  sudo service jetty2 status
  
  

  • If jetty run is not successful, then run this command
    update-rc.d <service> defaults (update-rc.d jetty2 defaults)

Https using CA certificate in jetty 

After obtaining the certificate file from the CA follow the below steps for configuration:

1.Converting certificate and private key to pfx or PKCS12 format

We need to convert the crt file  that is obtained from the CA to PKCS12 format. This can be done with the following steps:

1. Run the following command :

 openssl pkcs12 -inkey <privatekey.key> -in <certificate.crt> -export –out <certificate>.pkcs12

     2. Enter the pass phrase you have defined : <your password>

     3. Define an export password.(We have used same password  again; but you are free to alter it.)
     4. Enter the export password again: <your password>

After the above commands  pfx or pkcs12 file will be generated.

2.Importing the PKCS12 file in your Jetty keystore

We need to import the PKCS12 file in the keystore of Jetty.

The steps are listed below:

1. Copy the certificate.pkcs12 file to the directory JETTY_HOME/etc.
2. Delete the existing keystore file if present.
3. Execute the keytool import command:

keytool  -importkeystore  -srckeystore  <certificate.pkcs12> -srcstoretype  PKCS12 -destkeystore keystore

      4. Enter a password for the keystore.
      5. Re-type the password.
      6. Enter the password you have defined before for the PKCS12 file (<your password> that was used earlier in pfx generation).

Now we have created a new keystore and imported our PKCS12 file.

3.Enabling SSL and HTTPS for Jetty

Jetty 9 has a modular architecture, which means that you can enable different modules through the configuration files.

In order to enable HTTPS and Jetty, we have to follow these steps:

1. Open start.ini file which is in your JETTY_HOME directory.
2. Add following lines:

          --module=https
          etc/jetty-ssl.xml
         -DappConfig=service.properties
        -Djetty.logs=<JETTY_HOME>/logs (For data service, it is /opt/jetty/logs and For xconf admin , it is /opt/jetty2/logs)

      3. Passwords in Jetty configuration files are stored in an obfuscated form. This obfuscation is reversible and protects the passwords only from casual peeking.

We have defined the password  both for keystore and our certificate. Now we are going to obfuscate this password with the following steps:

•  Navigate to the JETTY_HOME/lib folder.
• Run following Java command (the lib version depends on your Jetty version):
  

   java -cp jetty-util-9.4.37.v20210219.jar org.eclipse.jetty.util.security.Password <your password>

• Copy the generated password, which is the line starting with OBF to your clipboard (a sample output is OBF:1wty1th11wgg1saj11v2h1sov1v1x1t371sar1wfi1thl1wug).

     4. XML files configuration

Jetty modules are configured through the XML files under JETTY_HOME/etc folder. By enabling these modules, we are activating jetty-ssl.xml and jetty-https.xml files.The following             changes need to be done in the below files:

1. jetty-ssl-context.xml

The obfuscated password generated in step 3 and the path for the keystore generated in JETTY_HOME/etc is updated  in the jetty-context.xml  :

2. jetty-ssl.xml

The port number for https connection need to be updated in this file. The following example has selected the port 9092 for xconf data service. For admin service, we have set it as 9093.

<Set name="port"><Property name="jetty.ssl.port" deprecated="ssl.port" default="9092" />