Install FAQ

Docker / Docker Compose

1

Why do I get the error, Error response from daemon: Get https://registry-1.docker.io/v2/: Service Unavailable, when pulling Docker images?

This error is commonly caused when there is no internet connectivity. Please check your internet connection and try again.

2

Why do I get the error, Error starting userland proxy: Bind for 0.0.0.0:9443 failed: port is already allocated?

This is because port 9443 is already being used by an existing process. Please stop that process or map the host port to a different port.

3

What is the Docker engine version required to run WSO2 Docker resources?

Use Docker engine release 17.06.0 or above.

4

Where do I report issues I encounter when running WSO2 products on Docker?

Each WSO2 product has a git repository containing the Docker resources. You can report issues against these git repositories.

WSO2 API Manager - https://github.com/wso2/docker-apim/issues

WSO2 Enterprise Integrator - https://github.com/wso2/docker-ei/issues

WSO2 Identity Server - https://github.com/wso2/docker-is/issues

WSO2 Stream Processor - https://github.com/wso2/docker-sp/issues

WSO2 IoT Server - https://github.com/wso2/docker-iot/issues

Install FAQ

Vagrant

1

Why do I get the error, Could not resolve host: vagrant.wso2.com, when running "vagrant up"?

This error is commonly caused when there is no internet connectivity. Please check your internet connection and try again.

2

Why do I see an error similar to This site can’t be reached, Connection refused or Unable to connect in the browser when accessing the WSO2 management console and/or applications?

This is probably because of a conflict between one of the IP addresses assigned to the virtual machine boxes and the host machine IP address. Edit the IP addresses given for the boxes in the config.yaml file.

3

Why does a box refuse to launch with an error similar to The forwarded port to 2222 is already in use on the host machine?

This is because port 2222 is already occupied. Kill the process or change the forwarding ports in config.yaml.

4

Where do I report issues I encounter when running WSO2 products on Vagrant?

Each WSO2 product has a corresponding git repository containing the Vagrant resources required to run the product on Vagrant. You can report issues against these git repositories.

WSO2 API Manager - https://github.com/wso2/vagrant-apim/issues

WSO2 Identity Server - https://github.com/wso2/vagrant-is/issues

WSO2 Enterprise Integrator - https://github.com/wso2/vagrant-ei/issues

WSO2 Stream Processor - https://github.com/wso2/vagrant-sp/issues

WSO2 IoT Server - https://github.com/wso2/vagrant-iot/issues

Install FAQ

Product Downloader

1

Why doesn't the product downloader start when I double click on the icon?

There are a few reason for this:

  1. The product downloader is not compatible with your operating system.
    • - You will have to resolve the missing/incompatible libraries in your system or contact us.
  2. A virus guard running on your system is preventing the product downloader from running.
    • - You will have to lower/disable the restriction from the virus guard temporarily or a href="https://wso2.com/contact/" target="_blank">contact us.
2

Why do I get the error, Error updating the product, after submitting my user credentials?

This may be due to an error while retrieving updates from the WSO2 Updates location or an issue related to your subscription. Please a href="https://wso2.com/contact/" target="_blank">contact us.

3

Why do I get the error, “There is a problem connecting to wso2 update, please try again”?

The product downloader has failed to connect with WSO2 Update service. Please try again after a while. If it still fails with the same message, please contact us

4

How can I use WUM behind a proxy server?

WUM is a command-line tool. Therefore, if you're using a proxy server, configure the proxy to allow WUM to access the WSO2 Update service. Allow the following two domains in the WSO2 Update service through your proxy service:

  1. https://api.updates.wso2.com/
  2. https://cdn.updates.wso2.com/

See the prerequisites for using WUM on how to configure the proxy.

Install FAQ

WSO2 Update Manager

1

Can I use updates without a paid subscription?

Yes, for that you have to have a “Free Trial Subscription”. For more information check our Free Trial Subscription page.

2

Do I need a key to unlock updates for production?

No. We trust our customers will adhere to the license terms. We make the terms clear to avoid accidental violations and reserve the right to remove access to updates or take other means to enforce the license against intentional violators.

Find out more about the EULA license.

3

Can I choose which updates to install?

No, you cannot choose the updates you want to install. This is because we test and certify each update on systems where all previous updates are installed, and it's not practical to test every arbitrary set of updates. However, you can always choose when to push a (coherent) set of updates into production.

Read more about moving updates into production.

4

Is WSO2 Update Manager (WUM) open source?

No. WUM and the WSO2 Update service are tightly coupled, and we are releasing WSO2 Updates with a commercial EULA license.

Find out more about the EULA license.

Find out more about the license terms for WSO2 Update Manager.

5

How can I use WUM behind a proxy server?

WUM is a command-line tool. Therefore, if you are using a proxy server, configure the proxy to allow WUM to access the WSO2 Update service. Allow the following two domains in the WSO2 Update service through your proxy service:

See the prerequisites for using WUM on how to configure the proxy.

6

How do I know when updates are available?

After you install WUM, run the "check update" command on your command line to check if updates are available for a given product. You can also automate this task using a script and schedule it to run periodically to see the available updates periodically.

See instructions on checking for available updates.

7

How can I know what changes are included in an update?

When you update a product using WUM, a new product distribution is created with the updates. You receive an email with information on all the updates included in the new distribution. You also find this information inside the new product distribution as a PDF file.

See instructions on verifying WUM updates.

8

How can I get the updates packaged separately?

You can compare two WUM-updated product distributions and generate a new ZIP file. This new ZIP file contains only the binaries that are different between the two distributions. You also receive an email along with a PDF, which contains information of the changes.

See instructions on generating a ZIP file with WUM updates.

Install FAQ

AWS CloudFormation

1

How to check the status of the deployed WSO2 services?

Check the Load Balancer health status of the instances using the AWS Management Console. The health status will be displayed under the “instances” tab in the corresponding Load Balancer.

2

How to log into an instance using SSH?

Since these instances are deployed in a private subnet, it is not possible to directly SSH into an instance. The CloudFormation template will create a Bastion instance (t2.micro) in a public subnet. Copy your key pair into the Bastion instance and SSH into that instance. From the Bastion instance, you may SSH into the preferred instance using its private IP address.

3

How to update product configurations using Puppet?

The provided CloudFormation templates use Puppet to manager configurations. Deploying the stack would create a Puppetmaster instance, which maintains all the product pattern configurations. If you need to change the configurations, simply SSH into the Puppetmaster instance using the steps in “How to log in to an instance using SSH?” and change the configurations available in the puppet modules. The relevant puppet modules are available at /etc/puppet/modules.

4

How to check whether the products are deployed with the latest updates?

If valid WUM credentials are provided to the CloudFormation template, the specific pattern would deploy the product with the latest updates. SSH into the Puppetmaster instance using the steps in “How to log in to an instance using SSH?”. The MOTD displayed when logging in will notify you about the status of the deployed WSO2 product pack and the license agreement.

5

Why do we require your AWSAccessKeyId and AWSAccessKeySecret?

These are used in two situations:

  1. For a couple of internal AWS CLI request calls
  2. For the AWS membership scheme in Hazelcast clustering

See the prerequisites for using WUM on how to configure the proxy.

6

How much will it cost me?

There is no additional charge for AWS CloudFormation. You only pay for the AWS resources that are created. (e.g. Amazon EC2 instances, elastic load balancing load balancers, etc.) The number of EC2 instances and the elastic load balancers depend on the product pattern.

Install FAQ

Kubernetes

1

What are Kubernetes resources for WSO2 products?

WSO2 product Kubernetes resources refer to Kubernetes artifacts that can be used to deploy the most commonly used WSO2 product patterns. WSO2 provides support for these Kubernetes artifacts. But please note that WSO2 does not provide Kubernetes support for its customers.

2

Do the Kubernetes resource deployments use WSO2 products with latest updates?

Yes, a Kubernetes deployment resource for any WSO2 product pattern is configured to pull the Docker image with latest updates corresponding to the product version every time it is deployed.

3

Why isn’t the external IP (under ADDRESS column in the output of `kubectl get ing`) visible for each of the deployed Ingress resources?

This is because the NGINX Ingress Controller has not been properly configured. Please follow the instructions provided in this guide in order to successfully install the Ingress Controller in the desired environment. In order to confirm whether the Ingress Controller was successfully installed, check whether a Kubernetes service named `ingress-nginx` along with an external IP has been deployed in the Kubernetes namespace named `ingress-nginx` as shown below:

4

How do I introduce additional configuration changes to a product deployment?

Currently, the minimum set of configurations required to successfully deploy a particular product deployment pattern using Kubernetes resources is provided using Kubernetes ConfigMaps. If any additional files with configuration changes, additional third-party libraries, OSGi bundles, and security related artifacts need to be added, a volume pre-populated with these artifacts, maintaining the folder structure of the relevant WSO2 product pack needs to be introduced. This volume needs to be mounted to the /home/wso2carbon/wso2-server-volume directory within the WSO2 product Docker container.

Please refer the following Kubernetes resource Git repository readme documentation for detailed examples on introducing additional configurations:

WSO2 API Manager - https://github.com/wso2/kubernetes-apim/blob/master/README.md

WSO2 Enterprise Integrator - https://github.com/wso2/kubernetes-ei/blob/master/README.md

WSO2 Identity Server - https://github.com/wso2/kubernetes-is/blob/master/README.md

WSO2 Stream Processor - https://github.com/wso2/kubernetes-sp/blob/master/README.md

5

How do I setup a pre-configured Network File System (NFS) server?

This may vary based on numerous factors such as the environment in which your Kubernetes cluster is deployed or your organizational restrictions. For example, if you have deployed your Kubernetes cluster in the Google Kubernetes Engine (GKE), you can make use of Google Cloud’s Single-Node File Server to setup NFS. In an AWS environment, you can setup NFS within an AWS EC2 instance residing within the same VPC as that of the Kubernetes node cluster.

6

Why do I need to provide WSO2 user credentials when deploying the Kubernetes resources?

WSO2 user credentials are required in order to create the Kubernetes Secret which is used to authenticate with WSO2 Private Docker Registry for pulling WSO2 product Docker images.

7

Why do I need to provide the cluster administrator credentials when deploying the Kubernetes resources?

Majority of the Kubernetes cluster solutions have Role Based Access Control (RBAC) enabled, by default. The Kubernetes resources for WSO2 products support clustered deployments of WSO2 products. During product clustering, a WSO2 product Kubernetes Pod instance uses the Kubernetes API to identify the other product cluster members. Hence, the cluster administrator credentials are required to create the Kubernetes Role and Role Binding, which provide the necessary permissions for communication with the Kubernetes API to the product pod instances.

8

Where do I report issues I encounter when running WSO2 products on Kubernetes?

Each WSO2 product has a corresponding Git repository containing the Kubernetes resources required to run the product on Kubernetes. You can report issues against these Git repositories:

WSO2 API Manager - https://github.com/wso2/kubernetes-apim

WSO2 Enterprise Integrator - https://github.com/wso2/kubernetes-ei

WSO2 Identity Server - https://github.com/wso2/kubernetes-is

WSO2 Stream Processor - https://github.com/wso2/kubernetes-sp

9

What are WSO2 simplified setups?

WSO2 simplified product setups are lightweight setups designed for you to quickly run and try out WSO2 products in Kubernetes environments.

These setups have certain features that do not affect the primary functionality disabled in them. They are recommended for look and feel but not for production instalments.

10

What is the difference between the WSO2 original setup and simplified setup?

We have removed clustering features in WSO2 simplified setups, so they are lightweight, and you can easily run them even in Minikube.

11

What are the minimum requirements to run the WSO2 Simplified setups in my machine?

You should either be a cluster-admin or you have the following privileges.

Resource Privileges
configmaps create, delete, get
namespaces create, delete
pods get, watch
pods/logs get, watch
secrets create, delete
serviceaccounts create, delete
services create, delete, get
deployments create, delete, get

To ensure smooth deployment, we recommend that you set the cluster memory to a minimum of 10GB and 2 CPUs.

12

How can I debug if it is not working?

Here are some basic commands for debugging well-known issues:

  1. To see details of your pods:

    kubectl get pods -n wso2

    This command returns the status of each pod along with other information, which helps you determine whether there is anything wrong with the deployment.

  2. To specifically inspect any pod:

    kubectl describe pods <pod-name(s)> -n wso2
  3. To view logs of any pod:

    kubectl logs -f <pod-name> -n wso2

    For more debugging information, see

13

Why is there an ‘image-pull-error’ appearing when I try to deploy?

This can either be a network issue (product images are not accessible) or due to incorrect/invalid credentials.

Check your network connection and re-run the setup. If you already have a subscription, make sure you provide correct credentials. If you do not have a subscription, use the open-source simplified setup to WSO2 products.

14

The setup is up and running, but I cannot access it through the browser. What should I do?

Private clusters do not have external IPs. Create a firewall rule to allow TCP traffic on your node’s ports. For example, if you are using Google Kubernetes Engine (GKE) as your cluster environment, run the following command:

gcloud compute firewall-rules create test-node-port --allow tcp:30000-32767
15

Which Kubernetes client version should I use?

Tested with version 1.12.5 and above.

Install FAQ

Helm

1

Why do I need to provide WSO2 user credentials when deploying the Helm package?

WSO2 user credentials are required in order to create the Kubernetes Secret which is used to authenticate with WSO2 Private Docker Registry for pulling WSO2 product Docker images.

2

How do I introduce additional product configurations to the deployment?

Currently, the minimum set of configurations required to successfully deploy a particular product deployment pattern using Kubernetes resources is provided using Kubernetes ConfigMaps. The files from which the ConfigMaps are created can be found in < /-conf/confs (e.g. /helm/, where is the root of the local copy of the Git repository containing the specific WSO2 product Kubernetes resources).

If any additional files with configuration changes, additional third-party libraries, OSGi bundles, and security related artifacts need to be added, a volume pre-populated with these artifacts, maintaining the folder structure of the relevant WSO2 product pack needs to be introduced. This volume needs to be mounted to the /home/wso2carbon/wso2-server-volume directory within the WSO2 product Docker container.

Please refer the following Kubernetes resource Git repository readme documentation for detailed examples on introducing additional configurations:

WSO2 API Manager -

WSO2 Enterprise Integrator -

WSO2 Identity Server -

WSO2 Stream Processor -

3

How do I setup a pre-configured Network File System (NFS) server?

This may vary based on numerous factors such as the environment in which your Kubernetes cluster is deployed or your organizational restrictions. For example, if you have deployed your Kubernetes cluster in the Google Kubernetes Engine (GKE), you can make use of Google Cloud’s Single-Node File Server to setup NFS. In an AWS environment, you can setup NFS within an AWS EC2 instance residing within the same VPC as that of the Kubernetes node cluster.

4

What is the update state of the WSO2 product?

Yes, a Kubernetes deployment resource for any WSO2 product pattern is configured to pull the Docker image with latest updates corresponding to the product version every time it is deployed.

WSO2 API Manager - https://github.com/wso2/kubernetes-apim/blob/master/README.md

WSO2 Enterprise Integrator - https://github.com/wso2/kubernetes-ei/blob/master/README.md

WSO2 Identity Server - https://github.com/wso2/kubernetes-is/blob/master/README.md

WSO2 Stream Processor - https://github.com/wso2/kubernetes-sp/blob/master/README.md

5

Where do I report issues I encounter when running WSO2 products using Helm?

Each WSO2 product has a corresponding Git repository containing the Helm resources required to run the product on Kubernetes. You can report issues against these Git repositories:

WSO2 API Manager - https://github.com/wso2/kubernetes-apim

WSO2 Enterprise Integrator - https://github.com/wso2/kubernetes-ei

WSO2 Identity Server - https://github.com/wso2/kubernetes-is

WSO2 Stream Processor - https://github.com/wso2/kubernetes-sp

Install FAQ

apt

1

Should we install Java before installing the product?

No. Since there is an embedded compatible JDK in the package, products run on top of it so there’s no need to install Java.

2

Can we upgrade the product?

No, you can’t. WSO2 maintains each version of the product as a separate package. So do not try to upgrade the version. Instead, if you want to use the next version of the product you simply have to remove or purge the product and install another package.

3

Why do we have to run a product in the terminal as product-version instead of just product name?
E.g. We have to run wso2am-2.6.0 instead of just wso2am

This is because WSO2 maintains each version of a product separately. So someone can install wso2am-2.5.0 and wso2am-2.6.0 in the same machine and run them separately.

4

Why apt-get update fails with the following error even though the package source is already added to the apt/source.list?

W: GPG error: https://dl.bintray.com/wso2/deb apim_260 Release: The following signatures couldn't be verified because the public key is not available: NO_PUBKEY 379CE192D401AB61
                                
E: The repository 'https://dl.bintray.com/wso2/deb apim_260 Release' is not signed.
N: Updating from such a repository can't be done securely, and is therefore disabled by default.
N: See apt-secure(8) manpage for repository creation and user configuration details.

This is because the apt-key is not added. Please run the command to add the apt-key before running the apt-get update.
You can add it with the following command:

apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys "379CE192D401AB61"
                                
5

Why does my installation fail with the following error?

Err:1 https://dl.bintray.com/wso2/deb apim_260/release amd64 wso2am-2.6.0 amd64 2.6.0
                            
Temporary failure resolving 'dl.bintray.com'
E: Failed to fetch https://dl.bintray.com/wso2/deb/pool/w/wso2am-2.6.0/wso2am-linux-installer-x64-2.6.0.deb Temporary failure resolving 'dl.bintray.com'
E: Unable to fetch some archives, maybe run apt-get update or try with --fix-missing?

This happens when there is no Internet connectivity at the time of installation. Please make sure that you have Internet connectivity to install the product via apt-get.

6

Where can I find the installed package path?

In any Debian system, WSO2 products will be installed to /usr/lib/wso2/product/version/.

Eg: WSO2 API Manager 2.6.0 will be installed to /usr/lib/wso2/wso2am/2.6.0/

7

Why do you we need to start the server with sudo permissions?

The installer requires sudo permissions to switch the user to wso2 user and start the server.

Install FAQ

YUM

1

Should we install Java before installing the product?

No. Since there is an embedded compatible JDK in the package, products run on top of it so there’s no need to install Java.

2

Can we upgrade the product?

No, you can’t. WSO2 maintains each version of the product as a separate package. So do not try to upgrade the version. Instead, if you want to use the next version of the product you simply have to remove or purge the product and install another package.

3

Why do we have to run a product in the terminal as product-version instead of just product name?
E.g. We have to run wso2am-2.6.0 instead of just wso2am

This is because WSO2 maintains each version of a product separately. So someone can install wso2am-2.5.0 and wso2am-2.6.0 in the same machine and run them separately.

4

Why does my installation fail with the following error?

No package wso2am-2.6.0.x86_64 available
                                

This is because wso2 package repo files are not updated correctly. Please run the following commands in the terminal:

1. wget https://bintray.com/wso2/rpm/rpm -O bintray-wso2-rpm.repo
                                
2. sudo mv bintray-wso2-rpm.repo /etc/yum.repos.d/
3. yum update
5

Why does my installation fail with the following error?

wso2am-linux-installer-x64-2.6 FAILED
                                
https://dl.bintray.com/wso2/rpm/wso2am-linux-installer-x64-2.6.0.rpm: [Errno 14] curl#6 - "Could not resolve host: dl.bintray.com; Unknown error"-:--:-- ETA
Trying other mirror.
Error downloading packages:
wso2am-2.6.0-2.6.0-1.x86_64: [Errno 256] No more mirrors to try.

This happens when there is no Internet connectivity for package installation.

6

Where can I find the installed package path?

In any Redhat system, WSO2 products will be installed to /usr/lib64/wso2/product/version/.

Eg: WSO2 API Manager 2.6.0 will be installed to /usr/lib64/wso2/wso2am/2.6.0/

7

Why do you we need to start the server with sudo permissions?

The installer requires sudo permissions to switch the user to wso2 user and start the server.

Install FAQ

Brew

1

Should we install Java before installing the product?

No. Since there is an embedded compatible JDK in the package, products run on top of it so there’s no need to install Java.

2

Can we upgrade the product?

No, you can’t. WSO2 maintains each version of the product as a separate package. So do not try to upgrade the version. Instead, if you want to use the next version of the product you simply have to remove or purge the product and install another package.

3

Why do we have to run a product in the terminal as product-version instead of just product name?
E.g. We have to run wso2am-2.6.0 instead of just wso2am

This is because WSO2 maintains each version of a product separately. So someone can install wso2am-2.5.0 and wso2am-2.6.0 in the same machine and run them separately.

4

Why does my installation fail with the following error trying to install WSO2 API Manager 2.6.0?

curl: (7) Couldn't connect to server
                                    
Error: An exception occurred within a child process:
DownloadError: Failed to download resource "wso2am-2.6.0"
Download failed: https://bintray.com/wso2/binary/download_file?file_path=wso2am-2.6.0.zip

This happens when there is no Internet connectivity at the time of installation. Please make sure that you have Internet connectivity to install the product via brew.

5

Where can I find the installed package path?

Run the following to show the installation path of a package:

brew info <package>

Example output:

wso2am-2.6.0: stable 2.6.0
                                    
WSO2 API Manager 2.6.0
https://wso2.com/api-management/
/usr/local/Cellar/wso2am-2.6.0/2.6.0 (4,658 files, 697.5MB) *
Built from source on 2018-10-09 at 11:53:29
From: https://github.com/Homebrew/homebrew-core/blob/master/Formula/wso2am-2.6.0.rb
==> Requirements
Required: java = 1.8 ✔