Skip to end of metadata
Go to start of metadata

If you are in a production environment, make sure to have the following ports open:

  • 5223 - TCP port used by devices to communicate to APNs servers
  • 2195 - TCP port used to send notifications to APNs
  • 2196 - TCP port  used by the APNs feedback service
  • 443 - TCP port used as a fallback on Wi-Fi, only when devices are unable to communicate to APNs on port 5223
    The APNs servers use load balancing. The devices will not always connect to the same public IP address for notifications. The entire address block is assigned to Apple, so it is best to allow this range in the firewall settings. 
  • 10397 - Thrift client and server ports
  • 8280, 8243 - NIO/PT transport ports

WSO2 IoT Server is configured via localhost as the product has SSO enabled by default. However, when configuring WSO2 IoT Server with iOS, you need to make it IP or hostname based instead of localhost so that the iOS agent can communicate with the Server. Follow the steps given below to configure the IP or hostname in WSO2 IoT Server. 

Configuring the IP using the script

This section provides a script that automatically configures the IP address when executed. This method is recommended because manually configuring the IP address includes many steps which may cause errors if not followed carefully. 

  1. Thie 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.

    If you want to configure the steps manually, see Configuring the IP or hostname manually and if you want to change the default ports, see Changing the Default Ports.

    1. Navigate to the <IOTS_HOME>/scripts directory.
    2. Run the change-ip script.

      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 chris@wso2.com as the email.


        Fully qualified domain name of your server.

  2. Navigate to the <IOTS_HOME>/ios-configurator directory.

    You will not have this directory if you did not follow the steps given in Installing iOS Features.

  3. To configure WSO2 IoT Server with the IP, run the ios.sh script with the IP addresses as arguments. 

    This part of the script creates a key pair, generates a signature, and signs the key using the signature. Next, you will be prompted for an IP address. 

    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.


Configuring the IP manually

This section provides detailed steps on how to configure the IP address manually (as an alternative to using the script given above). 

  1. Configure WSO2 IoT Server with the IP:

    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/iot-server.sh 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.

      -Diot.analytics.host="<IoT_SERVER_IP/HOSTNAME>" \
      -Diot.manager.host="<IoT_SERVER_IP/HOSTNAME>" \
      -Dmqtt.broker.host="<IoT_SERVER_IP/HOSTNAME>" \
      -Diot.core.host="<IoT_SERVER_IP/HOSTNAME>" \
      -Diot.keymanager.host="<IoT_SERVER_IP/HOSTNAME>" \
      -Diot.gateway.host="<IoT_SERVER_IP/HOSTNAME>" \
      -Diot.apimpublisher.host="<IoT_SERVER_IP/HOSTNAME>" \
      -Diot.apimstore.host="<IoT_SERVER_IP/HOSTNAME>" \
    8. Open the <IOTS_HOME>/wso2/analytics/bin/wso2.server.sh 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.

      -Dmqtt.broker.host="<IoT_SERVER_IP/HOSTNAME>" \
      -Diot.keymanager.host="<IoT_SERVER_IP/HOSTNAME>" \
      -Diot.gateway.host="<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 androidAgentDownloadURL property.

      "androidAgentDownloadURL": "https://%iot.manager.host%:%iot.manager.https.port%/android-web-agent/public/mdm.page.enrollments.android.download-agent/asset/android-agent.apk",
    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.

      Because of the changes made to the keystore, you will not able to access the tenants that are already created in WSO2 IoT Server. Therefore, it is recommended to keep a backup of the tenants when changing the IP or hostname.

      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 DER -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 13.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.

  2. Update the following parameters in the ios-config .xml file, which is in the <IoT_HOME>/conf directory: 
    Enter the server IP or the server domain name for the following parameters:

    • iOSEnrollURL

    • iOSProfileURL

    • iOSCheckinURL

    • iOSServerURL TokenURL

    For example:

    <?xml version="1.0" encoding="ISO-8859-1"?>
        <!-- iOS MDM endpoint urls -->
  3. Open the <IoTS_HOME>/conf/iot-api-config.xml file and replace localhost with your IP or hostname.
    For example: 

        <!-- IoT server host name, this is referred from APIM gateway to call to IoT server for certificate validation-->
        <!--End point to verify the certificate-->
        <!--Admin username/password - this is to use for oauth token generation-->
        <!--Dynamic client registration endpoint-->
        <!--Oauth token endpoint-->

What's next?

Next, follow the instructions in the Configuring WSO2 IoT Server to Install iOS Applications topic. 

  • No labels