This documentation is for WSO2 IoT Server 3.1.0. View the documentation for the latest release.
Product Administration - IoT Server 3.1.0 - WSO2 Documentation
Skip to end of metadata
Go to start of metadata

WSO2 Internet of Things Server (WSO2 IoT Server) is shipped with default configurations that will allow you to download, install and get started with your product instantly. However, when you go into production, it is recommended to change some of the default settings to ensure that you have a robust system that is suitable for your operational needs. Also, you may have specific use cases that require specific configurations to the server.

If you are a product administrator, the following content will provide an overview of the administrative tasks that you need to perform when working with WSO2 Internet of Things Server (WSO2 IoT Server).

Clustering WSO2 IoT Server

For information on how to set up a WSO2 IoT Server worker/manager separated cluster and how to configure a cluster with a third-party load balancer, see the Clustering Guide.

Changing the default database

By default, WSO2 products are shipped with an embedded H2 database, which is used for storing user management and registry data. We recommend that you use an industry-standard RDBMS such as Oracle, PostgreSQL, MySQL, MS SQL, etc. when you set up your production environment.  You can change the default database configuration by simply setting up a new physical database and updating the configurations in the product server to connect to that database. 

For instructions on setting up and configuring databases, see Working with Databases in the WSO2 IoT Server Guide.

Configuring users, roles, and permissions

The user management feature in your product allows you to create new users and define the permissions granted to each user. You can also configure the user stores that are used for storing data related to user management.

  • For instructions on how to configure users, roles and permissions, see User Management in the WSO2 IoT Server Guide. 
  • For instructions on how to configure the user realm and user stores, see the following topics in the WSO2 Product Administration Guide:
Configuring the System AdministratorThe admin user is the super tenant that will be able to manage all other users, roles and permissions in the system by using the management console of the product. Therefore, the user that should have admin permissions is required to be stored in the primary user store when you start the system for the first time. The documentation on setting up primary user stores will explain how to configure the administrator while configuring the user store. The information under this topic will explain the main configurations that are relevant to setting up the system administrator.
Configuring the Authorization ManagerAccording to the default configuration in WSO2 products, the users, roles and permissions are stored in the same repository (i.e., the default, embedded H2 database). However, you can change this configuration in such a way that the users and roles are stored in one repository (user store) and the permissions are stored in a separate repository. A user store can be a typical RDBMS, an LDAP or an external Active Directory. 

The repository that stores permissions should always be an RDBMS. The Authorization Manager configuration in the user-mgt.xml file (stored in the <PRODUCT_HOME>/conf/ directory) connects the system to this RDBMS. The information under this topic will instruct you through setting up and configuring the Authorization Manager.  

Configuring User Stores

The user management feature in WSO2 products allows you to maintain multiple user stores for your system that are used to store the users and their roles. The following topics guide you through configuring the user stores:

Configuring UsersTo enable users to log into the management console, you create user accounts and assign them roles, which are sets of permissions. You can add individual users or import users in bulk.

Configuring security

After you install WSO2 IoT Server, it is recommended to change the default security settings according to the requirements of your production environment. As WSO2 IoT Server is built on top of the WSO2 Carbon Kernel, the main security configurations applicable to IoT Server are inherited from the Carbon kernel.

For instructions on configuring security on your server, see the following topics in the WSO2 Product Administration Guide.

Configuring Transport-Level Security

The transport level security protocol of the Tomcat server is configured in the <PRODUCT_HOME>/conf/tomcat/catalina-server.xml file. Note that the ssLprotocol attribute is set to "TLS" by default. 
The following topics will guide you through the configuration options:

Using Asymmetric Encryption

WSO2 products use asymmetric encryption by default for the purposes of authentication and data encryption. In asymmetric encryption, keystores (with key pairs and certificates) are created and stored for the product. It is possible to have multiple keystores so that the keys used for different use cases are kept unique. The following topics explain more details on keystores and how you can create a new key store and configure it with WSO2 IoT Server.

Additionally, to the common configurations listed under Configuring Keystores in WSO2 Products, you need to configure WSO2 IoT Server if you changed the keystore from the default WSO2 keystore and changed the default WSO2 IP.

For more information, see Configuring Keystores in WSO2 IoT Server.

Using Symmetric Encryption

WSO2 Carbon-based products use asymmetric encryption by default as explained in the previous section. From Carbon 4.4.3 onwards, you have the option of switching to symmetric encryption in your WSO2 product. Using symmetric encryption means that a single key will be shared for encryption and decryption of information. 

Enabling Java Security Manager

The Java Security Manager is used to define various security policies that prevent untrusted code from manipulating your system.  Enabling the Java Security Manager for WSO2 products activates the Java permissions that are in the <PRODUCT_HOME>/core/repository/conf/sec.policy file. You modify this file to change the Java security permissions as required.

Securing Passwords in Configuration Files

All WSO2 Carbon products contain some configuration files with sensitive information such as passwords. Let's take a look at how such plain text passwords in configuration files can be secured using the Secure Vault implementation that is built into Carbon products.

The following topics will be covered under this section:

Resolving Hostname Verification

Hostname verification is enabled in WSO2 products by default, which means that when a hostname is being accessed by a particular client, it will be verified against the hostname specified in the product's SSL certificate.  

Configuring multitenancy

You can create multiple tenants in your product server, which will allow you to maintain tenant isolation in a single server/cluster. For instructions on configuring multiple tenants for your server, see Tenant Management in the WSO2 IoT Server Guide.

Configuring the registry

registry is a content store and a metadata repository for various artifacts such as services, WSDLs and configuration files. In WSO2 products, all configurations pertaining to modules, logging, security, data sources and other service groups are stored in the registry by default. 

For instructions on setting up and configuring the registry for your server, see Working with the Registry in the WSO2 Product Administration Guide.

Performance tuning

You can optimize the performance of your production server by configuring the appropriate OS settings, JVM settings etc. Most of these are server-level settings that will improve the performance of any WSO2 product. For instructions, see Performance Tuning in the WSO2 Product Administration Guide.

Additionally, check out the following sections to further optimize the performance of WSO2 IoT Server.

Changing the default ports

When you run multiple WSO2 products, multiple instances of the same product, or multiple WSO2 product clusters on the same server or virtual machines (VMs), you must change their default ports with an offset value to avoid port conflicts.

For instructions on configuring ports, see Changing the Default Ports in the WSO2 IoT Server Guide.

Installing, uninstalling and managing product features

Each WSO2 product is a collection of reusable software units called features where a single feature is a list of components and/or other feature. By default, WSO2 IoT Server is shipped with the features that are required for your main use cases. 

Configuring custom proxy paths

This feature is particularly useful when multiple WSO2 products (fronted by a proxy server) are hosted under the same domain name. By adding a custom proxy path you can host all products under a single domain and assign proxy paths for each product separately. 

For instructions on configuring custom proxy paths, see  Adding a Custom Proxy Path in the WSO2 Product Administration Guide.  

Customizing error pages

You can make sure that sensitive information about the server is not revealed in error messages, by customizing the error pages in your product. For instructions, see  Customizing Error Pages in the WSO2 Product Administration Guide.  

Customizing the management console

Some of the WSO2 products, such as WSO2 DSS consist of a web user interface named the management console. This allows administrators to configure, monitor, tune, and maintain the product using a simple interface. You can customize the look and feel of the management console for your product.

For instructions, see  Customizing the Management Console in the WSO2 Product Administration Guide.

Applying patches

For information on updating WSO2 IoT Server with the latest available patches (issued by WSO2) using the WSO2 Update Manager (WUM), see Updating WSO2 Products in the WSO2 Administration Guide.

Updating WSO2 Products with WUM

The  WSO2 Update Manager (WUM)  is a command-line utility that allows you to get the latest updates that are available for a particular product release. These updates include the latest bug fixes and security fixes that are released by WSO2 after a particular product version is released. Therefore, you do not need to wait and upgrade to the next product release to get these bug fixes.

For instructions on updating WSO2 IoT Server with WUM, see Getting Started with WUM in the WSO2 Product Administration Guide. 

Working with certificates in IoT Server

See Certificate Management for information and instructions on establishing a trust relationship between the IoT server and the client using mutual SSL authentication.


Monitoring is an important part of maintaining a product server. Listed below are the monitoring capabilities that are available for WSO2 IoT Server.

  • JMX-based monitoring: For information on monitoring your server using JMX, see JMX-based monitoring in the WSO2 Product Administration Guide.
  • Device monitoring: For information on configuring the monitoring frequency of devices enrolled with WSO2 IoT Server, see General Platform Configurations.
  • Monitoring server logs:  A properly configured logging system is vital for identifying errors, security threats and usage patterns in your production server. 
    For instructions on monitoring the server logs, see the following topics in the WSO2 Product Administration Guide. 
Monitoring Logs using Management Console

Monitoring logs using the management console of your product is possible with the Logging Management feature. To use this feature, see the following topics:

HTTP Access Logging HTTP Requests/Responses are logged in the access log(s) and are helpful to monitor your application's usage activities, such as the persons who access it, how many hits it receives, what the errors are etc. This information is useful for troubleshooting. As the runtime of WSO2 products is based on Apache Tomcat, you can use the Access_Log_Valve variable in Tomcat 7, as explained in this topic, to configure HTTP access logs in WSO2 products.

You can also customize the access logs based on the supported Access Log Valve attributes.  

Configuring with Other Products

Want to configure WSO2 IoT Server with WSO2 API Manager, WSO2 Identity Server, WSO2 Data Analytics Server or a third party MQTT broker? Check out the sub sections given below:

Required ports for WSO2 IoT Server

The following ports need to be opened for WSO2 IoT Server, and Android and iOS devices so that it can connect to Google Cloud Messaging (GCM)/Firebase Cloud Messaging (FCM) and APNS (Apple Push Notification Service), and enroll to WSO2 IoT Server.

Default Ports


HTTPS gateway port.
9443HTTPS port for the core profile.

HTTP gateway port.

9763HTTP port for the core profile.
1886Default MQTT port.
9445HTTPS port for the analytics profile.
9765HTTP port for the analytics profile.

HTTPS port to publish thrift data in the analytics profile


HTTP port to publish thrift data in the analytics profile

9446HTTPS port for the broker profile.
9766HTTP port for the broker profile.

Ports required for mobile devices to communicate with the server and the respective notification servers.





The ports to open are 5228, 5229 and 5230. Google Cloud Messaging (GCM) and Firebase Cloud Messaging (FCM) typically only use 5228, but it sometimes uses 5229 and 5230.
GCM/FCM does not provide specific IPs, so it is recommended to allow the firewall to accept outgoing connections to all IP addresses contained in the IP blocks listed in Google's ASN of 15169. 

5223Transmission Control Protocol (TCP) port used by devices to communicate to APNs servers.
2195TCP port used to send notifications to APNs.
2196TCP port  used by the APNs feedback service

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. 

  • No labels