This documentation is for WSO2 IoT Server 3.1.0. View the documentation for the latest release.
Configuring the IP or Hostname - IoT Server 3.1.0 - WSO2 Documentation
Skip to end of metadata
Go to start of metadata

WSO2 IoT Server is configured via localhost as the product has SSO enabled by default. In a production environment or if you want to make WSO2 IoT Server IP or hostname based instead of localhost, you need to configure it accordingly. Let's take a look at the steps you need to follow to configure WSO2 IoT Server with the IP:

Before you begin

You need to open the ports listed under Required ports for WSO2 IoT Server for WSO2 IoT Server to connect to Google Cloud Messaging (GCM)/Firebase Cloud Messaging (FCM) and Apple Push Notification Service (APNS), and enroll devices.

Configuring the IP or hostname using the script

This script automatically configures the IP and creates the required SSL certificates for the IP or hostname. This method is recommended because manually configuring the IP address includes many steps and if you miss out on a step you will run into errors.

  1. Navigate to the <IOTS_HOME>/scripts directory.
  2. Run the change-ip script.
    Example: Running the script on a Mac or Linux OS.


    Tip: The script will find and replace the IP address given in argument1 (localhost) with the IP address given as argument2 (, in the necessary configuration files. 

    1. Change the current IP address of the IoT Server core, broker, and analytics profile.

    2. Enter the values for IoT Server core SSL certificate.

       Click here for more information.

      Enter the requested information when prompted.

      CountryThe name of your country. Enter the two digit code for your country.
      StateThe state your organization is at.
      LocationThe city your organization is located at.


      The name of your organization. For this scenario, we entered wso2.

      Organization UnitDefined the Team ID as the organization unit.


      The email is used to identify the existing users. For this scenario, we entered [email protected] as the email.


      Fully qualified domain name of your server.

If you run the script once and access the device management console using the Chrome browser, it works perfectly. But, if you run the script for the second time and access the device management console via the Chrome browser, you will run into an error.

To avoid this, you can try out any of the options given below:

  • Option 1:
    Use another browser, such as Fire Fox, instead of the Chrome browser.
  • Option 2:
    Open the script, change the value defined for the set_serial property in the command given below to a different 8 digit number, and save the file. You need to do this after running the script for the first time.

    Note: Make sure to have a unique serial number each time you run the script.

    openssl x509 -req -days 730 -in ./tmp/c.csr -signkey ./tmp/c.key -set_serial 044324884 -out ./tmp/c.crt

If you run the script and if you are getting following error message;

[IoT-Core] ERROR - {org.apache.synapse.transport.passthru.TargetHandler} I/O error: Host name verification failed for host : {IoT_SERVER_HOSTNAME} Host name verification failed for host : {IoT_SERVER_HOSTNAME}

To avoid this, Add the following host entry into the /etc/hosts file.	{IoT_SERVER_HOSTNAME}

Configuring the IP or hostname manually

  1. Open the <IOTS_HOME>/conf/carbon.xml file and configure the <HostName> and <MgtHostName> attributes with the {IoT_SERVER_HOSTNAME}.

  2. Open the <IOTS_HOME>/conf/identity/sso-idp-config.xml file, and find and replace localhost with the <IoT_SERVER_IP/HOSTNAME >.

  3. Open the <IOTS_HOME>/conf/api-manager.xml file and configure the <DASServerURL> attribute by replacing localhost with the IoT Server IP or hostname.

  4. Open the <IOTS_HOME>/conf/etc/webapp-publisher-config.xml file, and set true as the value for <EnabledUpdateApi>.

    <!-- If it is true, the APIs of this instance will be updated when the webapps are redeployed -->

    If you have not started WSO2 IoT Server previously, you don't need this configuration. When the server starts for the first time it will update the APIs and web apps with the new server IP.

    Make sure to configure this property back to false if you need to restart the server again after the configuring the IP.

    By enabling the update API property, the APIs and the respective web apps get updated when the server restarts. This takes some time. Therefore, if you need to restart the server many times after this configuration or when in a production environment, you need to revert back to the default setting.

  5. Open the <IOT_HOME>/repository/deployment/server/jaggeryapps/api-store/site/conf/site.json file, and configure the identityProviderUrl attribute by replacing localhost with the IoT Server IP or hostname.

    "identityProviderURL" : "https://<IoT_SERVER_IP/HOSTNAME>:9443/samlsso",
  6. Open the <IOT_HOME>/wso2/analytics/repository/deployment/server/jaggeryapps/portal/configs/designer.json file, and configure the identityProviderUrlacs, and host attributes by replacing localhost with the IoT Server IP or hostname and the respective profiles port.

    "identityProviderURL": "https://<IoT_SERVER_IP/HOSTNAME>:9443/samlsso",
    "acs": "https://<IoT_SERVER_IP/HOSTNAME>:9445/portal/acs",

    The default port of the WSO2 IoT Server profiles are as follows:

    WSO2 IoT Server core profile9443
    WSO2 IoT Server analytics profile9445
    WSO2 IoT Server broker profile9446

    Therefore, the analytics portal needs to be assigned the 9445 port.

  7. Open the <IOTS_HOME>/bin/ file and configure the following properties by replacing localhost with the <IoT_SERVER_IP/HOSTNAME>. If you are running on Windows, you need to configure the iot-server.bat file."<IoT_SERVER_IP/HOSTNAME>" \"<IoT_SERVER_IP/HOSTNAME>" \"<IoT_SERVER_IP/HOSTNAME>" \"<IoT_SERVER_IP/HOSTNAME>" \"<IoT_SERVER_IP/HOSTNAME>" \"<IoT_SERVER_IP/HOSTNAME>" \"<IoT_SERVER_IP/HOSTNAME>" \"<IoT_SERVER_IP/HOSTNAME>" \
  8. Open the <IOTS_HOME>/wso2/analytics/bin/ file and configure the following properties by replacing localhost with the <IoT_SERVER_IP/HOSTNAME>. If you are running on Windows, you need to configure the wso2server.bat file."<IoT_SERVER_IP/HOSTNAME>" \"<IoT_SERVER_IP/HOSTNAME>" \"<IoT_SERVER_IP/HOSTNAME>" \
  9. Open the <IOTS_HOME>/wso2/broker/conf/broker.xml file and configure the following properties by replacing localhost with the <IoT_SERVER_IP/HOSTNAME>:

    <authenticator class="org.wso2.carbon.andes.authentication.andes.OAuth2BasedMQTTAuthenticator">
       <property name="hostURL">https://<IoT_SERVER_IP/HOSTNAME>:9443/services/OAuth2TokenValidationService</property>
       <property name="username">admin</property>
       <property name="password">admin</property>
       <property name="maxConnectionsPerHost">10</property>
       <property name="maxTotalConnections">150</property>
    <authorizer class="org.wso2.carbon.andes.extensions.device.mgt.mqtt.authorization.DeviceAccessBasedMQTTAuthorizer">
       <property name="username">admin</property>
       <property name="password">admin</property>
       <property name="tokenEndpoint">https://<IoT_SERVER_IP/HOSTNAME>t:8243</property>
       <!--offset time from expiry time to trigger refresh call - seconds -->
       <property name="tokenRefreshTimeOffset">100</property>
       <property name="deviceMgtServerUrl">https://<IoT_SERVER_IP/HOSTNAME>t:8243</property>
  10. Optionally, if you are using the WSO2 Android auto-enrollment feature, you need to replace all the localhost references to the IP or hostname in the following files that are in the

    <IOTS_HOME>/repository/deployment/server/synapse-configs/default/api directory.
    • admin--Android-Mutual-SSL-Event-Receiver.xml
    • admin--Android-Mutual-SSL-Device-Management.xml
    • admin--Android-Mutual-SSL-Configuration-Management.xml
  11. If you are using the hostname instead of the IP, open the <IOTS_HOME>/repository/deployment/server/jaggeryapps/devicemgt/app/conf/config.json file and configure the host property.

    "generalConfig": {
        "host": "<ENTER_THE_HOSTNAME>",
  12. Run the following commands so that the self-signed certificate refers to the IP you just configured instead of localhost.

    This step is required if your devices are accessing WSO2 IoT Server from outside the server.

    1. Navigate to the <IOTS_HOME>/repository/resources/security directory and run the following commands to create the client-truststore.jks and wso2carbon.jks files with the new IP or hostname.

      keytool -delete -alias wso2carbon -keystore wso2carbon.jks
      keytool -genkey -alias wso2carbon -keyalg RSA -keysize 2048 -keystore wso2carbon.jks -dname "CN=<IOT_SERVER_IP/HOSTNAME>,
      OU=Home,O=Home,L=SL,S=WS,C=LK" -storepass wso2carbon -keypass wso2carbon
      keytool -delete -alias wso2carbon -keystore client-truststore.jks
      keytool -export -alias wso2carbon -keystore wso2carbon.jks -file wso2carbon.pem
      keytool -import -alias wso2carbon -file wso2carbon.pem -keystore client-truststore.jks -storepass wso2carbon
    2. Update the Identity Provider (IDP) with the new certificate:

      1. Export wso2carbon.pem certificate that is in the binary DER format to the ASCII PEM format.

        openssl x509 -inform dir -outform PEM -in wso2carbon.pem -out server.crt
      2. Open the server.crt file you just generated and copy the content that is between the BEGIN CERTIFICATE and END CERTIFICATE.

        Make sure to remove the new lines that are there in the certificate. Else, the JWT validation fails.

      3. Open the <IOTS_HOME>/conf/identity/identity-providers/iot_default.xml file and replace the content that is under the <Certificate> property with the content you just copied.

    3. Copy the client-truststore.jks and wso2carbon.jks files that you created in step 14.a to the following locations.

      Make sure to only copy the files. Don't remove it from the <IOTS_HOME>/repository/resources/security directory.

      • <IOTS_HOME>/wso2/broker/repository/resources/security

      • <IOTS_HOME>/wso2/analytics/repository/resources/security

  13. Once you are done with the above steps, restart or start the message broker, IoT Server core, and the analytics profiles in the given order. For more information, see Starting the Server.

  • No labels