Carbon Apps, or CAR Files are a deployable package consisting of WSO2 Product related artifacts. These artifacts can range from Synapse Sequences, Proxy Services, Registry items, to Dashboard Server Gadgets, Dashboards, Siddhi Execution Plans, to Tasks like Purging, NTask etc. For example, to group a set of artifacts to be deployed on WSO2 ESB, a CAR file can be used that has some Synapse Sequences, Proxy Services, APIs, and Endpoints. In essence, it’s a compressed Zip file with a different extension.
A Carbon App can be deployed on a WSO2 Server using different methods, however all those methods end up copying the CAR file to <CARBON_HOME>/repository/deployment/server/carbonapps folder. A continuous watcher that checks for content changes inside this folder would decompress the CAR file and execute respective deployers based on the artifact type (defined in the meta file artifact.xml).
So, if the target server is a localhost, it’s just a simple matter of copying the CAR file to the above location. However, things get a little complicated when the target server doesn’t provide shell access.
WSO2 Carbon exposes a set of administrative services that act as a SOAP based API to interact with the particular WSO2 Server. If the OSGi Console is enabled (by setting osgiConsole System Property), the total list of admin services can be displayed by issuing listAdminServices command on the OSGi prompt. For example, the list of admin services exposed in an ESB 4.9.0 server can be found out as follows.
./wso2server.sh -DosgiConsole
JAVA_HOME environment variable is set to /home/chamilad/dev/java/jdk1.8.0_77
CARBON_HOME environment variable is set to /home/chamilad/dev/wso2esb-4.9.0
Java HotSpot(TM) 64-Bit Server VM warning: ignoring option MaxPermSize=256m; support was removed in 8.0
OSGi console has been enabled with options: -console
osgi> [2016-09-16 01:00:45,715] INFO - CarbonCoreActivator Starting WSO2 Carbon...
[2016-09-16 01:00:45,718] INFO - CarbonCoreActivator Operating System : Linux 4.4.0-36-generic, amd64
[2016-09-16 01:00:45,718] INFO - CarbonCoreActivator Java Home : /home/chamilad/dev/java/jdk1.8.0_77/jre
[2016-09-16 01:00:45,718] INFO - CarbonCoreActivator Java Version : 1.8.0_77
....
....
....
....
....
[2016-09-16 01:01:06,987] INFO - CarbonUIServiceComponent Mgt Console URL : https://172.17.0.1:9443/carbon/
[Press ENTER]
osgi>
osgi>
osgi> listAdminServices
Admin services deployed on this server:
1. ModuleAdminService, ModuleAdminService, https://chamilad-ubuntu:8243/services/ModuleAdminService
2. TracerAdmin, TracerAdmin, https://chamilad-ubuntu:8243/services/TracerAdmin
3. InboundAdmin, InboundAdmin, https://chamilad-ubuntu:8243/services/InboundAdmin
4. TemplateAdminService, TemplateAdminService, https://chamilad-ubuntu:8243/services/TemplateAdminService
5. CustomUIAdminService, CustomUIAdminService, https://chamilad-ubuntu:8243/services/CustomUIAdminService
6. ThemeMgtService, ThemeMgtService, https://chamilad-ubuntu:8243/services/ThemeMgtService
7. MediationLibraryUploader, MediationLibraryUploader, https://chamilad-ubuntu:8243/services/MediationLibraryUploader
8. ListMetadataService, ListMetadataService, https://chamilad-ubuntu:8243/services/ListMetadataService
9. LoginStatisticsAdmin, LoginStatisticsAdmin, https://chamilad-ubuntu:8243/services/LoginStatisticsAdmin
10. PropertiesAdminService, PropertiesAdminService, https://chamilad-ubuntu:8243/services/PropertiesAdminService
11. PublishEventMediatorConfigAdmin, PublishEventMediatorConfigAdmin, https://chamilad-ubuntu:8243/services/PublishEventMediatorConfigAdmin
12. LoggingAdmin, LoggingAdmin, https://chamilad-ubuntu:8243/services/LoggingAdmin
13. LogViewer, LogViewer, https://chamilad-ubuntu:8243/services/LogViewer
14. NDataSourceAdmin, NDataSourceAdmin, https://chamilad-ubuntu:8243/services/NDataSourceAdmin
15. SearchAdminService, SearchAdminService, https://chamilad-ubuntu:8243/services/SearchAdminService
16. RestApiAdmin, RestApiAdmin, https://chamilad-ubuntu:8243/services/RestApiAdmin
17. WSDL2CodeService, WSDL2CodeService, https://chamilad-ubuntu:8243/services/WSDL2CodeService
18. BAMMediatorConfigAdmin, BAMMediatorConfigAdmin, https://chamilad-ubuntu:8243/services/BAMMediatorConfigAdmin
19. CustomMeteringService, CustomMeteringService, https://chamilad-ubuntu:8243/services/CustomMeteringService
20. UserAdmin, UserAdmin, https://chamilad-ubuntu:8243/services/UserAdmin
21. UserStoreConfigAdminService, UserStoreConfigAdminService, https://chamilad-ubuntu:8243/services/UserStoreConfigAdminService
22. TaskAdmin, TaskAdmin, https://chamilad-ubuntu:8243/services/TaskAdmin
23. CGAgentAdminService, CGAgentAdminService, https://chamilad-ubuntu:8243/services/CGAgentAdminService
24. WSDLValidatorService, WSDLValidatorService, https://chamilad-ubuntu:8243/services/WSDLValidatorService
25. SynapseArtifactUploaderAdmin, SynapseArtifactUploaderAdmin, https://chamilad-ubuntu:8243/services/SynapseArtifactUploaderAdmin
26. ServerAdmin, ServerAdmin, https://chamilad-ubuntu:8243/services/ServerAdmin
27. MediationTracerService, MediationTracerService, https://chamilad-ubuntu:8243/services/MediationTracerService
28. RelationAdminService, RelationAdminService, https://chamilad-ubuntu:8243/services/RelationAdminService
29. ServiceAdmin, ServiceAdmin, https://chamilad-ubuntu:8243/services/ServiceAdmin
30. PriorityMediationAdmin, PriorityMediationAdmin, https://chamilad-ubuntu:8243/services/PriorityMediationAdmin
31. ExternalTryitService, ExternalTryitService, https://chamilad-ubuntu:8243/services/ExternalTryitService
32. ConfigServiceAdmin, ConfigServiceAdmin, https://chamilad-ubuntu:8243/services/ConfigServiceAdmin
33. ProxyServiceAdmin, ProxyServiceAdmin, https://chamilad-ubuntu:8243/services/ProxyServiceAdmin
34. ResourceAdminService, ResourceAdminService, https://chamilad-ubuntu:8243/services/ResourceAdminService
35. EventBrokerService, EventBrokerService, https://chamilad-ubuntu:8243/services/EventBrokerService
36. StatisticsAdmin, StatisticsAdmin, https://chamilad-ubuntu:8243/services/StatisticsAdmin
37. KeyStoreAdminService, KeyStoreAdminService, https://chamilad-ubuntu:8243/services/KeyStoreAdminService
38. MessageProcessorAdminService, MessageProcessorAdminService, https://chamilad-ubuntu:8243/services/MessageProcessorAdminService
39. ESBNTaskAdmin, ESBNTaskAdmin, https://chamilad-ubuntu:8243/services/ESBNTaskAdmin
40. ProvisioningAdminService, ProvisioningAdminService, https://chamilad-ubuntu:8243/services/ProvisioningAdminService
41. MediationSecurityAdminService, MediationSecurityAdminService, https://chamilad-ubuntu:8243/services/MediationSecurityAdminService
42. RemoteTaskAdmin, RemoteTaskAdmin, https://chamilad-ubuntu:8243/services/RemoteTaskAdmin
43. ServerRolesManager, ServerRolesManager, https://chamilad-ubuntu:8243/services/ServerRolesManager
44. SecurityAdminService, SecurityAdminService, https://chamilad-ubuntu:8243/services/SecurityAdminService
45. ContentSearchAdminService, ContentSearchAdminService, https://chamilad-ubuntu:8243/services/ContentSearchAdminService
46. InfoAdminService, InfoAdminService, https://chamilad-ubuntu:8243/services/InfoAdminService
47. ManageGenericArtifactService, ManageGenericArtifactService, https://chamilad-ubuntu:8243/services/ManageGenericArtifactService
48. LoggedUserInfoAdmin, LoggedUserInfoAdmin, https://chamilad-ubuntu:8243/services/LoggedUserInfoAdmin
49. MessageStoreAdminService, MessageStoreAdminService, https://chamilad-ubuntu:8243/services/MessageStoreAdminService
50. TenantMgtAdminService, TenantMgtAdminService, https://chamilad-ubuntu:8243/services/TenantMgtAdminService
51. CarbonAppUploader, CarbonAppUploader, https://chamilad-ubuntu:8243/services/CarbonAppUploader 52. FileDownloadService, FileDownloadService, https://chamilad-ubuntu:8243/services/FileDownloadService
53. CommandMediatorAdmin, CommandMediatorAdmin, https://chamilad-ubuntu:8243/services/CommandMediatorAdmin
54. ServiceGroupAdmin, ServiceGroupAdmin, https://chamilad-ubuntu:8243/services/ServiceGroupAdmin
55. MediationStatisticsAdmin, MediationStatisticsAdmin, https://chamilad-ubuntu:8243/services/MediationStatisticsAdmin
56. DeploymentSynchronizerAdmin, DeploymentSynchronizerAdmin, https://chamilad-ubuntu:8243/services/DeploymentSynchronizerAdmin
57. ApplicationAdmin, ApplicationAdmin, https://chamilad-ubuntu:8243/services/ApplicationAdmin
58. EndpointAdmin, EndpointAdmin, https://chamilad-ubuntu:8243/services/EndpointAdmin
59. MediationStatPublisherAdmin, MediationStatPublisherAdmin, https://chamilad-ubuntu:8243/services/MediationStatPublisherAdmin
60. MediationLibraryAdminService, MediationLibraryAdminService, https://chamilad-ubuntu:8243/services/MediationLibraryAdminService
61. TopicManagerAdminService, TopicManagerAdminService, https://chamilad-ubuntu:8243/services/TopicManagerAdminService
62. SynapseApplicationAdmin, SynapseApplicationAdmin, https://chamilad-ubuntu:8243/services/SynapseApplicationAdmin
63. OperationAdmin, OperationAdmin, https://chamilad-ubuntu:8243/services/OperationAdmin
64. Java2WSDLService, Java2WSDLService, https://chamilad-ubuntu:8243/services/Java2WSDLService
65. LocalEntryAdmin, LocalEntryAdmin, https://chamilad-ubuntu:8243/services/LocalEntryAdmin
66. ThrottleAdminService, ThrottleAdminService, https://chamilad-ubuntu:8243/services/ThrottleAdminService
67. MultipleCredentialsUserAdmin, MultipleCredentialsUserAdmin, https://chamilad-ubuntu:8243/services/MultipleCredentialsUserAdmin
68. SequenceAdminService, SequenceAdminService, https://chamilad-ubuntu:8243/services/SequenceAdminService
69. STSAdminService, STSAdminService, https://chamilad-ubuntu:8243/services/STSAdminService
70. FlowsAdminService, FlowsAdminService, https://chamilad-ubuntu:8243/services/FlowsAdminService
71. RepositoryAdminService, RepositoryAdminService, https://chamilad-ubuntu:8243/services/RepositoryAdminService
72. RegistryAdminService, RegistryAdminService, https://chamilad-ubuntu:8243/services/RegistryAdminService
73. EndpointTemplateAdminService, EndpointTemplateAdminService, https://chamilad-ubuntu:8243/services/EndpointTemplateAdminService
74. WSDLToolService, WSDLToolService, https://chamilad-ubuntu:8243/services/WSDLToolService
75. DiscoveryAdmin, DiscoveryAdmin, https://chamilad-ubuntu:8243/services/DiscoveryAdmin
76. FileUploadService, FileUploadService, https://chamilad-ubuntu:8243/services/FileUploadService
77. ClassMediatorAdmin, ClassMediatorAdmin, https://chamilad-ubuntu:8243/services/ClassMediatorAdmin
Although all admin services are listed here, some of those are not exposed by default, and some do not have authorization parameters set. Therefore, those are blocked from being accessed. If these need to be desperately accessed follow {future blog post} steps.
Getting back to the topic, one of the admin services in this list is of interest to us. Using the service CarbonAppUploader, CAR files can be uploaded to the respective server. Let’s try this scenario using SoapUI for WSO2 ESB 4.9.0.
Service Definition
To call the CarbonAppUploader admin service, we have to create the clients from its WSDL. By default, the WSDLs of the admin services are hidden. If you don’t have any control over the server in question, or it cannot be restarted for reasons of service disruption, I’ve added the WSDL as a Gist. After downloading, replace server-host-or-ip with the hostname or the IP address of the ESB server.
If you have some control over the server, where you can restart the ESB server, you can directly obtain the WSDL from the server. First disable the setting that hides the WSDLs by default, by setting HideAdminServiceWSDLs to false in <CARBON_HOME>/repository/conf/carbon.xml.
<HideAdminServiceWSDLs>false</HideAdminServiceWSDLs>
After this you will able to obtain the WSDL of a service by appending ?wsdl to the end of the Service URL. For example, the WSDL of the CarbonAppUpload service of a locally run ESB server will be at the following location.
https://localhost:8243/services/CarbonAppUploader?wsdl
Notice the port mentioned in the above URL, 8243, and in the resulting WSDL, is different from the port that I have included in the WSDL in the Gist above? This is to do with the difference between the Servlet ports and the Synapse Mediation ports. Because Synapse accepts mediation through (by default) port 8243, the WSDL is shown on it. However the admin services are available through the Servlet port, 9443.
SoapUI Requests
Having obtained the WSDL, let’s proceed to create a SoapUI request from it.
Open SoapUI and create a new SOAP Project (File -> New SOAP Project). Provide the WSDL file (or the above ?wsdl URL). Check Create Requests so that SoapUI will create sample requests for the operations in the WSDL.
Click Ok and you will see the set of operations (in CarbonAppUploader, there is one operation, uploadApp) created in the SoapUI Project view.
Open Request1 under CarbonAppUploaderSoap11Binding.uploadApp and you will see the already created Soap Envelope with ? as a placeholder for values. For the uploadApp operation three inputs are needed.
- dataHandler — Base64 binary encoded file content
- fileName — File name of the CAR file
- fileType — File compression, only the value “jar” is supported
The port confusion comes in to play again. If you loaded the WSDL from the remote URL with 8243, you will have to change the port in the request from 8243 to 9443.
Attaching the CAR File
We need to serialize the CAR file as a base64 encoded string and add it in the SOAP request. SoapUI provides this functionality as Attachments.
On the request, click on Attachments, and then add CAR file as an attachment. Navigate to the CAR file and select it. Select No to cache the attachment, as I found it to sometimes upload the file in an incomplete manner.
Copy the value in the ContentID. This, along with the cid: prefix, has to be added as the dataHandler in the request.
After the attachment is done, the request will look like the following.
In addition to adding the attachment, MTOM has to be enabled in the request. This has to be done through setting Enable MTOM to true in the request properties.
Authentication
Click on Auth tab and add basic authentication to the request.
Upload the CAR File
We are all done now. What’s left is to just go ahead and make the SOAP request. The file will be uploaded, and a response will be returned, with the status of the upload. After a maximum of one minute, the Carbon App will be processed and the artifacts will be deployed.
Written on September 17, 2016 by chamila de alwis.
Originally published on Medium