Prerequisites¶
Prior to installing any WSO2 Identity Server, it is necessary tohave the appropriate prerequisite software installed on your system.Verify that the computer has the supported operating system anddevelopment platforms before starting the installation.
System requirements¶
Note
The below recommendations can change based on the expected concurrency & performance.
CPU | 4 vCPUs (x86_64 Architecture) |
---|---|
Memory | 4 GB RAM |
Disk | ~ 10 GB disk space, excluding space allocated for log files and databases. |
Environment compatibility¶
Operating Systems/ Databases/ Userstores |
Note
|
---|
Required applications¶
The following applications are required for running the product and itssamples or for building from the source code.
Note
The applications marked with an asterisk * are mandatory.
Required applications to run the product
These applications are mandatory and are required to run the binarydistribution of the WSO2 product.The binary distribution contains thebinary files for both MS Windows, and Linux-based operating systems.
Application | Purpose | Version | |
---|---|---|---|
Java SE Development Kit (JDK)* |
|
| |
Web Browser* |
Note: On Windows Server 2003, you must not go below the medium security level in Internet Explorer 6.x. |
Required applications to run samples and build from source
These applications are required for building the product from thesource distribution,andcompiling and running product samples.
Warning
If you are installing by downloading and extracting the binary distribution (as recommended for most users) instead of building from the source code, you do not need to install Maven.
Application | Purpose | Version | Download Links |
---|---|---|---|
Apache Maven |
| 3.0.x or later |
Install on different platforms¶
Install on Linux or OS X¶
Follow the instructions below to install WSO2 Identity Server on Linuxor Mac OS X.
Install the required applications
Log in to the command line (Terminal on Mac).
Ensure that your system meets the Installation Prerequisites. Java Development Kit (JDK) is essential to run the product.
Install WSO2 Identity Server
- Download the latest version of WSO2 Identity Server from http://wso2.com/products/identity-server/.
Extract the archive file to a dedicated directory for WSO2 Identity Server, which will hereafter be referred to as
<IS_HOME>
Warning
If you are using Mac OS with High Sierra, you may encounter thefollowing warning message when logging in to the management consoledue to a compression issue that exists in the High Sierra SDK.
WARN {org.owasp.csrfguard.log.JavaLogger} - potential cross-site request forgery (CSRF) attack thwarted (user:<anonymous>, ip:xxx.xxx.xx.xx, method:POST, uri:/carbon/admin/login_action.jsp, error:required token is missing from the request)
To avoid this issue,
1. Open thedeployment.toml
file in the<IS_HOME>/repository/conf/
directory.
2. Set thecompression
element under the HTTPS connector configuration tooff
.```[transport.https]...compression="off"... ```!!! note If the above configuration is not listed in `deployment.toml`, add the above configuration manually.
- Restart WSO2 Identity Server.
Set up JAVA_HOME
You must set your JAVA_HOME
environment variable topoint to the directory where the Java Development Kit (JDK) is installedon the computer.
Setting JAVA_HOME
is a standard practice when you are using Java based programs. You may not need to do this manually depending on your Java Installer, as this variable is usually set by the Java installer itself. This guide is provided in case the JAVA_HOME variable
has not been set or is incorrectly set on your machine.
Info
Environment variables are global system variables accessible by all the processes running under the operating system.
In your home directory, open theBASHRC file (.bash_profilefile
on Mac) using editors such as vi, emacs, pico, or mcedit.2. Assuming you have JDK 11.0.14 in your system, add the followingtwo lines at the bottom of the file, replacing
/usr/java/jdk-11.0.14
with the actualdirectory where the JDK is installed.export JAVA_HOME=/usr/java/jdk-11.0.14export PATH=${JAVA_HOME}/bin:${PATH}
export JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk-11.0.14/Contents/Home
Save the file.
Info
If you do not know how to work with text editors in a Linux SSH session, run the following command:
cat >> .bashrc.
. Paste the string from the clipboard and press Ctrl+D.To verify that the
JAVA_HOME
variable is set correctly, execute the following command:echo $JAVA_HOME
which java
If the above command gives you a path like /usr/bin/java, then it is a symbolic link to the real location. To get the real location, run the following:
ls -l `which java`
The system returns the JDK installation path.
Set system properties
If you need to set additional system properties when the server starts,you can take the following approaches:
- Set the properties from a script : Setting your system properties in the startup script is ideal, because it ensures that you set the properties every time you start the server. To avoid having to modify the script each time you upgrade, the best approach is to create your own startup script that wraps the WSO2 startup script and adds the properties you want to set, rather than editing the WSO2 startup script directly.
- Set the properties from an external registry : If you want to access properties from an external registry, you could create Java code that reads the properties at runtime from that registry. Be sure to store sensitive data such as username and password to connect to the registry in a properties file instead of in the Java code and secure the properties file with the cipher tool.
You are now ready to run the product
Install on Solaris¶
Follow the instructions below to install Identity Server on Solaris.
Install the required applications
- Establish an SSH connection to the Solaris machine or log in on the text console.
- Be sure your system meets the Installation Prerequisites. Java Development Kit (JDK) is essential to run the product.
Install WSO2 Identity Server
- Download the latest version of WSO2 Identity Server from http://wso2.com/products/identity-server/.
- Extract the archive file to a dedicated directory for WSO2 Identity Server, which will hereafter be referred to as
<IS_HOME>
Set up JAVA_HOME
You must set your JAVA_HOME
environment variable topoint to the directory where the Java Development Kit (JDK) is installedon the computer.
Setting JAVA_HOME
is a standard practice when you are using Java based programs. You may not need to do this manually depending on your Java Installer, as this variable is usually set by the Java installer itself. This guide is provided in case the JAVA_HOME variable
has not been set or is incorrectly set on your machine.
Info
Environment variables are global system variables accessible by all the processes running under the operating system.
- In your home directory, open theBASHRC file in your favorite text editor, such as vi, emacs, pico, or mcedit.
Assuming you have JDK 1.8.0_141in your system, addthe following two lines at the bottom of the file, replacing
/usr/java/jdk-11.0.14
with the actual directory where the JDK is installed.export JAVA_HOME=/usr/java/jdk-11.0.14export PATH=${JAVA_HOME}/bin:${PATH}
Save the file.
Info
If you do not know how to work with text editors in an SSH session, run the following command.
cat >> .bashrc
Paste the string from the clipboard and press "Ctrl+D".
To verify that the
JAVA_HOME
variable is set correctly, execute the following command.echo $JAVA_HOME
The system returns the JDK installation path.
Set system properties
If you need to set additional system properties when the server starts,you can take the following approaches:
- Set the properties from a script : Setting your system properties in the startup script is ideal, because it ensures that you set the properties every time you start the server. To avoid having to modify the script each time you upgrade, the best approach is to create your own startup script that wraps the WSO2 startup script and adds the properties you want to set, rather than editing the WSO2 startup script directly.
- Set the properties from an external registry : If you want to access properties from an external registry, you could create Java code that reads the properties at runtime from that registry. Be sure to store sensitive data such as username and password to connect to the registry in a properties file instead of in the Java code and secure the properties file with the cipher tool.
You are now ready to run the product
Install on Windows¶
Follow the instructions below to install the WSO2 Identity Server onWindows.
Install the required applications
- Ensure that your system meets the requirements specified in the Installation Prerequisites. Java Development Kit (JDK) is essential to run the product.
- Ensure that the
PATH
environment variable is set toC:\Windows\System32
, because thefindstr
Windows.exe file is stored in this path.
Install WSO2 Identity Server
- Download the latest version of WSO2 Identity Server from http://wso2.com/products/identity-server/.
Extract the archive file to a dedicated directory for WSO2 Identity Server, which will hereafter be referred to as
<IS_HOME>
Set the
CARBON_HOME
environment variable by pointing it to the directory where you download WSO2 Identity Server into. For more information on how to do this, see here.
Set up JAVA_HOME
You must set your JAVA_HOME
environment variable topoint to the directory where the Java Development Kit (JDK) is installedon the computer. Typically, the JDK is installed in a directory underC:/Program Files/Java
, such asC:/Program Files/Java/jdk-11.0.14
.If you havemultiple versions installed, choose the latest one, which you can findby sorting by date.
Info
Environment variables are global system variables accessible by all theprocesses running under the operating system. You can define anenvironment variable as a system variable, which applies to all users,or as a user variable, which applies only to the user who is currentlylogged in.
You set up JAVA_HOME
using the System Properties, as described below.Alternatively, if you just want to set JAVA_HOME temporarily for thecurrent command prompt window, set it at the commandprompt.
Set up JAVA_HOME using the system properties
Right-click the My Computer icon on the desktop and choose Properties.
In the System Properties window, click the Advanced tab, and then click the Environment Variables button.
Click the New button under System variables (for all users) or under User variables (just for the user who is currently logged in).
Enter the following information:
- In the Variable name field, enter:
JAVA_HOME
- In the Variable value field, enter the installation path of the Java Development Kit, such as:
c:/Program Files/Java
jdk-11.0.14
- In the Variable name field, enter:
The JAVA_HOME
variable is now set and will apply to any subsequentcommand prompt windows you open. If you have existing command promptwindows running, you must close and reopen them for the JAVA_HOMEvariable to take effect, or manually set the JAVA_HOME variable inthose command prompt windows as described in the next section. To verifythat the JAVA_HOME
variable is set correctly, open acommand window (from the Start menu, click Run, and then typeCMD
and click Enter ) and execute the followingcommand.
set JAVA_HOME
The system returns the JDK installation path. You are now ready to runthe product.
Set JAVA_HOME temporarily using the Windows command prompt (CMD)
You can temporarily set the JAVA_HOME
environmentvariable within a Windows command prompt window (CMD). This is usefulwhen you have an existing command prompt window running and you do notwant to restart it.
In the command prompt window, enter the following command where
<JDK_INSTALLATION_PATH>
is the JDK installation directory and press Enter.Format
set JAVA_HOME=<JDK_INSTALLATION_PATH>
Example
set JAVA_HOME=c:/Program Files/java/jdk-11.0.14
The `JAVA_HOME variable is now set for the current CMD session only.
To verify that the
JAVA_HOME
variable is set correctly, execute the following command:set JAVA_HOME
The system returns the JDK installation path.
Set system properties
If you need to set additional system properties when the server starts,you can take the following approaches:
- Set the properties from a script : Setting your system properties in the startup script is ideal, because it ensures that you set the properties every time you start the server. To avoid having to modify the script each time you upgrade, the best approach is to create your own startup script that wraps the WSO2 startup script and adds the properties you want to set, rather than editing the WSO2 startup script directly.
- Set the properties from an external registry : If you want to access properties from an external registry, you could create Java code that reads the properties at runtime from that registry. Be sure to store sensitive data such as username and password to connect to the registry in a properties file instead of in the Java code and secure the properties file with the cipher tool.
You are now ready to run the product
Install as a Linux Service¶
WSO2 Carbon and any Carbon-based product can be run as a Linux serviceas described in the following sections:
Prerequisites
Install JDK and set up the JAVA_HOME
environmentvariable. For more information, seeInstallationPrerequisites.
Set up CARBON_HOME
Extract the WSO2 product that you want to run as a Linux service and setthe environment variable CARBON_HOME
to the extractedproduct directory location.
Run the product as a Linux service
To run the product as a service, create a startup script and add it to the boot sequence. The basic structure of the startup script has three parts (i.e., start, stop and restart) as follows:
#!/bin/bashcase "$1″ instart) echo "Starting Service";;stop) echo "Stopping Service";;restart) echo "Restarting Service";;*) echo $"Usage: $0 {start|stop|restart}"exit 1esac
Click to view an example startup script written for WSO2 Identity Server 5.9.0
#! /bin/sh### BEGIN INIT INFO# Provides: wso2is# Required-Start: $all# Required-Stop:# Default-Start: 2 3 4 5# Default-Stop:# Short-Description: starts the wso2 identity server### END INIT INFOexport JAVA_HOME="/usr/lib/jvm/jdk-11.0.14"startcmd='/opt/WSO2/wso2is-5.9.0/bin/wso2server.sh start > /dev/null &'restartcmd='/opt/WSO2/wso2is-5.9.0/bin/wso2server.sh restart > /dev/null &'stopcmd='/opt/WSO2/wso2is-5.9.0/bin/wso2server.sh stop > /dev/null &'case "$1" instart)echo "Starting WSO2 Identity Server ..."su -c "${startcmd}" user1;;restart)echo "Re-starting WSO2 Identity Server ..."su -c "${restartcmd}" user1;;stop)echo "Stopping WSO2 Identity Server ..."su -c "${stopcmd}" user1;;*)echo "Usage: $0 {start|stop|restart}"exit 1esac
In the above script, the server is started as a user by the nameuser1 rather than the root user.For example,
su -c "${startcmd}" user1
Add the script to
/etc/init.d/
directory.If you want to keep the scripts in a location other than
/etc/init.d/
folder, you can add a symboliclink to the script in/etc/init.d/
and keepthe actual script in a separate location. Say your script name isidentityserver and it is in/opt/WSO2/
folder, then the commands for adding a link to/etc/init.d/
is as follows:Make executable:
sudo chmod a+x /opt/WSO2/identityserver
Add a link to
/etc/init.d/
:sudo ln -snf /opt/WSO2/identityserver /etc/init.d/identityserver
Install the startup script to respective runlevels using the command
update-rc.d
.For example, give the following command for the sample script shown in step1:sudo update-rc.d identityserver defaults
The
defaults
option in the above commandmakes the service to start in runlevels 2,3,4 and 5 and to stop inrunlevels 0,1 and 6.Info
A runlevel is a mode of operation in Linux (or any Unix-styleoperating system). There are several runlevels in a Linux server andeach of these runlevels is represented by a single digit integer.Each runlevel designates a different system configuration and allowsaccess to a different combination of processes.
You can now start, stop and restart the server using
service <service name>
{start|stop|restart}
command. You will be prompted for the password of the user (or root) who was used to start the service.
Install as a Windows Service¶
Any Java-based application, including WSO2 Carbon and Carbon-basedproducts, can be run as a Windows service by using a bridging tool suchasYet Another Java Service Wrapper (YAJSW).
Info
As YAJSW is distributed under the LGPL license and WSO2 isdistributed under the Apache2 license, these two cannot be packedtogether in a distribution. However, any end-user or customer can freelycombine components under these two licenses as long as the combined workis not distributed. The following instructions will guide you via the process of using YAJSW to install WSO2 Identity Server as a Windows Service.
Follow the instructions in the sections below to set it up.
Prerequisites
- Install JDK and set up the
JAVA_HOME
environment variable.For more information, see InstallationPrerequisites. - Download and install a service wrapper library for running WSO2 Identity Server as a Windows service. WSO2 recommends Yet Another Java Service Wrapper ( YAJSW ) version 13.03, and several WSO2 products provide a default
wrapper.conf
file in their<PRODUCT_HOME>/bin/yajsw/
directory. The following instructions describe how to set up this file.
Set up the YAJSW wrapper configuration file
wrapper.conf
file is used for wrapping Java Applications by YAJSW. The wrapper.conf
file found in the<IS_HOME>/bin/yajsw/
directory holds the minimalconfiguration for running a WSO2 product as a Windows Service.
Copy the
wrapper.conf
file found in the<IS_HOME>/bin/yajsw/
directory and paste it in the<YAJSW_HOME>/conf/
directory.
A samplewrapper.conf
file that is packed with the WSO2 product is given below.Info
If you wish to set additional properties from an external registryat runtime, store sensitive information like usernames and passwordsfor connecting to the registry in a properties file, and secure itwith the cipher tool.
Click to view a sample
#********************************************************************# working directory#********************************************************************wrapper.working.dir=${carbon_home}/# Java Main class.# YAJSW: default is "org.rzo.yajsw.app.WrapperJVMMain"# DO NOT SET THIS PROPERTY UNLESS YOU HAVE YOUR OWN IMPLEMENTATION# wrapper.java.mainclass=#********************************************************************# tmp folder# yajsw creates temporary files named in_.. out_.. err_.. jna..# per default these are placed in jna.tmpdir.# jna.tmpdir is set in setenv batch file to <yajsw>/tmp#********************************************************************wrapper.tmp.path = ${jna_tmpdir}#********************************************************************# Application main class or native executable# One of the following properties MUST be defined#********************************************************************# Java Application main classwrapper.java.app.mainclass=org.wso2.carbon.bootstrap.Bootstrap# Log Level for console output. (See docs for log levels)wrapper.console.loglevel=INFO# Log file to use for wrapper output logging.wrapper.logfile=${wrapper_home}\/log\/wrapper.log# Format of output for the log file. (See docs for formats)#wrapper.logfile.format=LPTM# Log Level for log file output. (See docs for log levels)#wrapper.logfile.loglevel=INFO# Maximum size that the log file will be allowed to grow to before# the log is rolled. Size is specified in bytes. The default value# of 0, disables log rolling by size. May abbreviate with the 'k' (kB) or# 'm' (mB) suffix. For example: 10m = 10 megabytes.# If wrapper.logfile does not contain the string ROLLNUM it will be automatically added as suffix of the file namewrapper.logfile.maxsize=10m# Maximum number of rolled log files which will be allowed before old# files are deleted. The default value of 0 implies no limit.wrapper.logfile.maxfiles=10# Title to use when running as a consolewrapper.console.title=WSO2 Carbon#********************************************************************# Wrapper Windows Service and Posix Daemon Properties#********************************************************************# Name of the servicewrapper.ntservice.name=WSO2CARBON# Display name of the servicewrapper.ntservice.displayname=WSO2 Carbon# Description of the servicewrapper.ntservice.description=Carbon Kernel#********************************************************************# Wrapper System Tray Properties#********************************************************************# enable system traywrapper.tray = true# TCP/IP port. If none is defined multicast discovery is used to find the port# Set the port in case multicast is not possible.wrapper.tray.port = 15002#********************************************************************# Exit Code Properties# Restart on non zero exit code#********************************************************************wrapper.on_exit.0=SHUTDOWNwrapper.on_exit.default=RESTART#********************************************************************# Trigger actions on console output#********************************************************************# On Exception show message in system traywrapper.filter.trigger.0=Exceptionwrapper.filter.script.0=${wrapper_home}/scripts/trayMessage.gvwrapper.filter.script.0.args=Exception#********************************************************************# genConfig: further Properties generated by genConfig#********************************************************************placeHolderSoGenPropsComeHere=wrapper.java.command = javawrapper.java.classpath.1 = ${carbon_home}/bin/*.jarwrapper.java.classpath.2 = ${carbon_home}/lib/commons-lang-*.jarwrapper.java.classpath.3 = ${carbon_home}/lib/*.jarwrapper.app.parameter.1 = org.wso2.carbon.bootstrap.Bootstrapwrapper.app.parameter.2 = RUNwrapper.java.additional.1 = -Xbootclasspath/a:${carbon_home}/lib/xboot/*.jarwrapper.java.additional.2 = -Xms256mwrapper.java.additional.3 = -Xmx1024mwrapper.java.additional.4 = -XX:+HeapDumpOnOutOfMemoryErrorwrapper.java.additional.5 = -XX:HeapDumpPath=${carbon_home}/repository/logs/heap-dump.hprofwrapper.java.additional.6 = -Dcom.sun.management.jmxremotewrapper.java.additional.7 = -Dcarbon.registry.root=\/wrapper.java.additional.8 = -Dcarbon.home=${carbon_home}wrapper.java.additional.9 = -Dwso2.server.standalone=truewrapper.java.additional.10 = -Djava.command=${java_home}/bin/javawrapper.java.additional.11 = -Djava.io.tmpdir=${carbon_home}/tmpwrapper.java.additional.12 = -Dcatalina.base=${carbon_home}/lib/tomcatwrapper.java.additional.13 = -Djava.util.logging.config.file=${carbon_home}/repository/conf/etc/logging-bridge.propertieswrapper.java.additional.14 = -Dcarbon.config.dir.path=${carbon_home}/repository/confwrapper.java.additional.15 = -Dcarbon.logs.path=${carbon_home}/repository/logswrapper.java.additional.16 = -Dcomponents.repo=${carbon_home}/repository/components/pluginswrapper.java.additional.17 = -Dconf.location=${carbon_home}/repository/confwrapper.java.additional.18 = -Dcom.atomikos.icatch.file=${carbon_home}/lib/transactions.propertieswrapper.java.additional.19 = -Dcom.atomikos.icatch.hide_init_file_path=truewrapper.java.additional.20 = -Dorg.apache.jasper.runtime.BodyContentImpl.LIMIT_BUFFER=truewrapper.java.additional.21 = -Dcom.sun.jndi.ldap.connect.pool.authentication=simplewrapper.java.additional.22 = -Dcom.sun.jndi.ldap.connect.pool.timeout=3000wrapper.java.additional.23 = -Dorg.terracotta.quartz.skipUpdateCheck=truewrapper.java.additional.24 = -Dorg.apache.jasper.compiler.Parser.STRICT_QUOTE_ESCAPING=falsewrapper.java.additional.25 = -Dfile.encoding=UTF8wrapper.java.additional.26 = -DworkerNode=falsewrapper.java.additional.27 = -Dhttpclient.hostnameVerifier=DefaultAndLocalhostwrapper.java.additional.28 = -Dcarbon.new.config.dir.path=${carbon_home}/repository/resources/conf
Set up carbon_home
Extract the Carbon-based product that you want to run as a Windowsservice, and then set the Windows environment variable carbon_home
to the extracted product directory location. For example, if you want torun WSO2 IS 5.11.0 as a Windows service, you would set carbon_home
to theextracted wso2is-5.11.0
directory.
Run the product in console mode
You will now verify that YAJSW is configured correctly for running theCarbon-based product as a Windows service.
Open a Windows command prompt and go to the
<YAJSW_HOME>/bat/
directory. For example:cd C:\Documents and Settings\yajsw_home\bat
Start the wrapper in console mode using the following command:
runConsole.bat
If the configurations are set properly for YAJSW, you will see consoleoutput similar to the following. Now you can access the WSO2 managementconsole from your web browser via https://localhost:9443/carbon.
Work with theWSO2CARBONservice
To install the Carbon-based product as a Windows service, open a console with administrative privileges and execute thefollowing command in the <YAJSW_HOME>/bat/
directory:
installService.bat
The console will display a message confirming thattheWSO2CARBONservice has been installed.
To start the service, execute the following command in the same consolewindow (with administrative privileges):
startService.bat
The console will display a message confirming thattheWSO2CARBONservice has been started.
To stop the service, execute the following command in the same consolewindow (with administrative privileges):
stopService.bat
The console will display a message confirming thattheWSO2CARBONservice has been stopped.
To uninstall the service, execute thefollowing command in the sameconsole window (with administrative privileges):
uninstallService.bat
The console will display a message confirming thattheWSO2CARBONservice has been removed.
Uninstall the product¶
To remove analready installed product, follow the instructions below:
OS | Instructions |
---|---|
Mac OS | Open a terminal and run the following command as the root user: |
Windows | C:/Program Files/WSO2/<PRODUCT_NAME>/<VERSION> |
Ubuntu | Open a terminal and run the following command: |
CentOS | Open a terminal and run the following command: |