Skip to content

admin_Customizing the Management Console

See the following topics to do customizations to the management console:

Changing the management console's URL

When you start a WSO2 server, the URL of the management console will be printed on the terminal. The URL format is as follows: https://<Server Host>:<Management Console Port>/carbon/. When accessing the management console from the same server where it is installed, you can type localhost instead of the IP address.

You can change the URL by modifying the value of the <MgtHostName> property in the <EI_HOME>/conf/carbon.xml file. When the host is internal or not resolved by a DNS, map the hostname alias to its IP address in the /etc/hosts file of your system, and then enter that alias as the value of the <MgtHostName> property in carbon.xml . For example:

    In /etc/hosts:
    127.0.0.1       localhost
In carbon.xml:
<MgtHostName>localhost</MgtHostName>

Configuring the session time-out

If you leave the management console unattended for a defined time, its login session will time out. The default timeout value is 15 minutes, but you can change this in the <PRODUCT_HOME>/repository/conf/tomcat/carbon/WEB-INF/web.xml file as follows.

html/xml <session-config> <session-timeout>15</session-timeout> </session-config>

Changing the management console's interface

The user interfaces of every Carbon product allows you to configure, monitor, tune, and maintain the product. The components that formulate the design and style of these user interfaces are defined in resource (JAR) files.

The user interface of every Carbon product consists of two layers:

  • The common product layout/design inherited from the Carbon platform: All the common templates, styles (CSS files), and images are stored in the Carbon core UI bundle, which is named org.wso2.carbon.ui-<version-number>.jar ( <version-number> is the particular version of the bundle). This bundle is responsible for the overall look and feel of the entire Carbon platform.

  • The styles/images unique to each product: Each Carbon product (that is built on Carbon kernel) has another style bundle, which contains all the overriding style sheets and images: org.wso2.<product-name>.styles-<version-number>.jar .

You can customize the user interfaces by modifying these resource files. You need to create a fragment bundle for the original resource file. Then, you can pack the modified resource files in the required bundle. The files in the required bundle will get precedence and will override the files in the original bundle.

You can use this same technique to customize any aspect of the user interfaces. The advantage of this technique is that you will not lose your customizations when you apply official patches to the product by replacing the original bundles.

For example, when you access the Management Console using the following URL, by default, it has the WSO2 product logo as shown below: https://10.100.5.72:9443/carbon/

Info

Note that the images and instructions given on this page are valid for WSO2 products that are based on Carbon 4.4.x.

current logo of the Management Console

Follow the steps below to customize the above management console by changing the logo.

  1. Open the <PRODUCT_HOME>/repository/components/plugins/ directory. You need to find the bundle that contains the resource files that you want to modify. In this case, the logo and the related CSS files are contained in the org.wso2.carbon.ui_<version-number>.jar file. Copy the org.wso2.carbon.ui_<version-number>.jar file to a separate location on your computer, and extract the file. Note the symbolic name of this bundle, which is ' org.wso2.carbon.ui_<version-number> '.

  2. Create a new Maven project using your IDE. Be sure to include the symbolic name of the original bundle that you extracted in the previous step (which is ' org.wso2.carbon.ui_<version-number> ') in the Maven project name. For example, you can use org.wso2.carbon.ui_<version-number>_patch as the Maven project name.

  3. Add the following content to the pom.xml file of the org.wso2.carbon.ui_<version-number>_patch project. In this pom.xml file, be sure to replace the <version-number> of org.wso2.carbon.ui_<version-number>_patch with the correct version value.

    ``` xml <?xml version="1.0" encoding="UTF-8"?> 4.0.0 org.wso2.carbon org.wso2.carbon.ui__patch 1.0.0 bundle

    &lt;build&gt;
        &lt;plugins&gt;
            &lt;plugin&gt;
                &lt;groupId&gt;org.apache.felix&lt;/groupId&gt;
                &lt;artifactId&gt;maven-bundle-plugin&lt;/artifactId&gt;
                &lt;version&gt;3.0.1&lt;/version&gt;
                &lt;extensions&gt;true&lt;/extensions&gt;
                &lt;configuration&gt;
                    &lt;instructions&gt;
                        &lt;Bundle-SymbolicName&gt;${project.artifactId}&lt;/Bundle-SymbolicName&gt;
                        &lt;Bundle-Name&gt;${project.artifactId}&lt;/Bundle-Name&gt;
                        &lt;Export-Package&gt;web.admin.*&lt;/Export-Package&gt;
                    &lt;/instructions&gt;
                &lt;/configuration&gt;
            &lt;/plugin&gt;
        &lt;/plugins&gt;
    &lt;/build&gt;

    ``` 4. Create directories in your Maven project as explained below.

    1. Create the /web folder under the /src/main/resources directory of the org.wso2.carbon.ui_<version-number>_patch project.

    2. Then, create the /admin directory under /web.

    3. Finally, create the /css, /images , and /layout directories under /admin .

    Your org.wso2.carbon.ui_<version-number>_patch project should now look as shown below. 5. Create a new CSS file (e.g. customizations.css ) with the following content.

    css #header div#header-div div.left-logo { background-image: url( ../images/new-logo.png ); background-repeat: no-repeat; background-position: left top; background-size: contain; height: 40px; width: 300px; margin-top: 23px; margin-left: 20px; float: left; }

    !!! tip

    This file includes the logo customization styles.

  4. Add the customizations.css file to the <org.wso2.carbon.ui_<version-number>_patch>/src/main/resources/web/admin/css/ directory.

  5. Locate the template.jsp file that is in the org.wso2.carbon.ui_<version-number>.jar bundle, which you extracted in step 1 above. You will find template.jsp file inside the <org.wso2.carbon.ui_<version-number>.jar>/web/admin/layout/ directory. Then, copy this file to the <org.wso2.carbon.ui_<version-number>_patch>/src/main/resources/web/admin/layout/ directory.

  6. Locate the following line in the <org.wso2.carbon.ui_<version-number>_patch>/src/main/resources/web/admin/layout/template.jsp file, which you added in the previous step:

    java <link href="<%=globalCSS%>" rel="stylesheet" type="text/css" media="all"/>

  7. Replace the above line with the following:

    java <link href="../admin/css/customizations.css" rel="stylesheet" type="text/css" media="all"/>

  8. Add the below image as the new logo (e.g. new-logo.png ) to the <org.wso2.carbon.ui_<version-number>_patch>/src/main/resources/web/admin/images/ directory.

    new logo

  9. Create another Maven project using your IDE. Be sure to include the symbolic name of the original bundle that you extracted in step 1 above (which is ' org.wso2.carbon.ui_<version-number> ') in the project name. For example, you can use org.wso2.carbon.ui_<version-number>_fragment as the Maven project name.

    !!! info

    This creates a project for the fragment bundle. Since the symbolic name of the original bundle is ‘ org.wso2.carbon.ui ’, the fragment host value of this bundle should be the same (e.g. org.wso2.carbon.ui_<version-number>_fragment ). This fragment bundle will not contain anything (expect the pom.xml file) when it is built.

  10. Add the following content to the pom.xml file of the org.wso2.carbon.ui_<version-number>_fragment project. In this pom.xml file, replace the <version-number> of org.wso2.carbon.ui_<version-number>_patch and org.wso2.carbon.ui_<version-number>_fragment with the correct version value.

    !!! info

    This pom.xml file of the fragment bundle defines properties, which includes the required bundle value (i.e. ‘ org.wso2.carbon.ui_<version-number>_patch ’).

    ``` xml <?xml version="1.0" encoding="UTF-8"?> 4.0.0 org.wso2.carbon org.wso2.carbon.ui__fragment 1.0.0 bundle

    &lt;build&gt;
        &lt;plugins&gt;
            &lt;plugin&gt;
                &lt;groupId&gt;org.apache.felix&lt;/groupId&gt;
                &lt;artifactId&gt;maven-bundle-plugin&lt;/artifactId&gt;
                &lt;version&gt;3.0.1&lt;/version&gt;
                &lt;extensions&gt;true&lt;/extensions&gt;
                &lt;configuration&gt;
                    &lt;instructions&gt;
                        &lt;Bundle-SymbolicName&gt;${project.artifactId}&lt;/Bundle-SymbolicName&gt;
                        &lt;Bundle-Name&gt;${project.artifactId}&lt;/Bundle-Name&gt;
                        &lt;Require-Bundle&gt;org.wso2.carbon.ui_&lt;version-number&gt;_patch&lt;/Require-Bundle&gt;
                        &lt;Fragment-Host&gt;org.wso2.carbon.ui&lt;/Fragment-Host&gt;
                    &lt;/instructions&gt;
                &lt;/configuration&gt;
            &lt;/plugin&gt;
        &lt;/plugins&gt;
    &lt;/build&gt;

    `` 13. Now you can build the two projects. Open a terminal, navigate to the relevant project directory (listed above), and execute the following command: mvnclean install.-org.wso2.carbon.ui__fragment`

    -org.wso2.carbon.ui_<version-number>_patch

  11. Once the project is built, copy the two JAR files listed below (from the <PROJECT_HOME>/target/ directory) to the <PRODUCT_HOME>/repository/components/dropins/ directory. -org.wso2.carbon.ui_<version-number>_fragment-1.0.0.jar

    -org.wso2.carbon.ui_<version-number>_patch-1.0.0.jar

  12. Restart the WSO2 product server.

  13. Access the management console of your WSO2 product using the following URL: https://10.100.5.12:9443/carbon/ . You view the new logo, which the patch bundle contains as shown below.

    Management Console with the new logo

admin_Customizing Error Pages

WSO2 Carbon servers display errors, exceptions, and HTTP status codes in full detail. These are known as Verbose error messages. These error messages contain technical details such as stack traces. There may also disclose other sensitive details. Attackers may fingerprint the server, based on the information disclosed in error messages. Alternatively, attackers may attempt to trigger specific error messages to obtain technical information about the server. You can avoid these situations by configuring the server to display generic, non-detailed error messages in Apache Tomcat.

From Carbon 4.4.6 onwards, the pages that should be displayed on a certain throwable exception, error or an HTTP status code are specified in the <CARBON_HOME>repository/conf/tomcat/carbon/WEB-INF/web.xml file. You can customize those error pages as preferred. For example, if you try to access a resource that is not available in the Carbon server (e.g., https://10.100.5.72:9443/abc ), you will view the error page as follows: " Error 404 - Not Found ".

You can customize the above error message by following the instructions given below.

  1. Download and install Apache Maven .

  2. Create a Maven project using your IDE.

  3. Create a directory named resources inside the <PROJECT_HOME>/src/main/ directory, and then create another directory named web inside it.

    !!! tip

    <PROJECT_HOME> denotes the top-level directory of your Maven project.

  4. Create a new HTML error page (e.g. new_error_404.html file) as shown below. This contains the customized error page.

    xml <html> <head> <meta http-equiv="content-type" content="text/html; charset=ISO-8859-1"> <title>404 - Error not found</title> </head> <body> <h1>Sorry, this resource is not found.</h1> </body> </html>

  5. Add the new_error_404.html file inside the <PROJECT_HOME>/src/main/web directory.

  6. Add the following property below the <version> element in the <PROJECT_HOME>/pom.xml file: <packaging>bundle</packaging>

  7. Add the following configurations inside the <plugins> element in the <PROJECT_HOME>/pom.xml file.

    xml <plugin> <groupId>org.apache.felix</groupId> <artifactId>maven-bundle-plugin</artifactId> <extensions>true</extensions> <configuration> <instructions> <Bundle-SymbolicName>${project.artifactId}</Bundle-SymbolicName> <Bundle-Name>${project.artifactId}</Bundle-Name> <Import-Package> org.osgi.framework, org.osgi.service.http, org.wso2.carbon.ui, javax.servlet.*;version="2.4.0", *;resolution:=optional </Import-Package> <Fragment-Host>org.wso2.carbon.ui</Fragment-Host> <Carbon-Component>UIBundle</Carbon-Component> </instructions> </configuration> </plugin>

  8. Add the following configurations inside the <dependencies> element in the <PROJECT_HOME>/pom.xml file:

    xml <dependency> <groupId>org.apache.felix</groupId> <artifactId>org.apache.felix.framework</artifactId> <version>1.0.3</version> </dependency>

  9. Build the Maven project by executing the following command: mvn clean install

  10. Once the project is built, copy the JAR file (from the <PROJECT_HOME>/target/ directory) to the <CARBON_HOME>/repository/components/dropins/ directory.

  11. Change the following configurations in the <CARBON_HOME>/repository/conf/tomcat/carbon/WEB-INF/web.xml file.

    text <error-page> <error-code>404</error-code> <location>/carbon/new_error_404.html</location> </error-page>

    !!! tip

    You need to replicate this configuration, and change the values of the <error-code> and <location> elements accordingly for each new HTML error page you add.

  12. Restart the WSO2 Carbon server.

  13. Access the following URL again, to test the error page you customized: https://10.100.5.72:9443/abc. You will view the new error page with the following content: " Sorry, this resource is not found. "
Top