Previous page Part II, Chapter 5, Section 1. Starting xxeserver on Linux or on macOS Part II, Chapter 5, Section 2. Starting xxeserver on Windows (10 / 25)   Table of Contents   Index Part II, Chapter 6. Integrating an XML editor into your web application Next page

2. Starting xxeserver on Windows Previous topic Parent topic Child topic Next topic

Let's suppose XMLmind XML Editor Web Edition (XXEW) has been installed in C:\xxe\ and that SSL certificate cert_192_168_1_26.pfx (where 192.168.1.26 is the IP address of your computer) has been copied to C:\xxe\web\etc\.
On Windows, C:\xxe\web\bin\xxeserver.bat is of little use as there is no way to keep this command running after you close the Command Prompt used to execute the command and even less, after you log out from the computer.
On Windows, the only way to keep xxeserver running after you log out from the computer is to install it and start it as a system service. This is achieved by using Windows Service Wrapper Opens in new window (WinSW), a quality, proven, open source software.

Checking that xxeserver works on your computer

Before using C:\xxe\web\bin\xxeservice.exe (which is just a renamed WinSW.exe), make sure that xxeserver actually works on your computer. This preliminary step is useful to check the following:
  1. Your anti-virus software does not prevent xxeserver from starting.
  2. Windows firewall does not block xxeserver connections.
  3. The port used by xxeserver, by default 18078 (or 18079 if a SSL certificate has been specified as a command-line option), is available.
Procedure:
  1. Open a Command Prompt as an administrator and run xxeserver. 
    C:\xxe\web\bin> xxeserver.batenter_key.png
  2. In the address bar of your web browser, type "http://localhost:18078/xxe/" then select New|New Local Document to create a document of any kind and finally click Close to close this blank document.
  3. Type Ctrl-C in the Command Prompt to shutdown xxeserver.

How to operate xxeservice

  1. Open a Command Prompt as an administrator in order to install and start xxeservice. 
    C:\xxe\web\bin> xxeservice.exe install
C:\xxe\web\bin> xxeservice.exe start
C:\xxe\web\bin> xxeservice.exe status
    install
    Install the service, that is, register it with Windows service manager.
    start
    Start the service.
    status
    Check the current status of the service: NonExistent (service not installed), Started (service is running) or Stopped (service installed but not running).
    Remember that xxeservice.exe is just a renamed WinSW.exe, therefore more information about xxeservice (that is, WinSW) sub-commands is found in Usage Opens in new window.
  2. In the address bar of your web browser, type "http://localhost:18078/xxe/" then select New|New Local Document to create a document of any kind and finally click Close to close this blank document.
  3. If you are curious, restart your computer and repeat previous step to check that xxeservice is still running after the computer is restarted.
  4. Open a Command Prompt as an administrator in order to stop and uninstall xxeservice. 
    C:\xxe\web\bin> xxeservice.exe stop
C:\xxe\web\bin> xxeservice.exe status
C:\xxe\web\bin> xxeservice.exe uninstall
    stop
    Stop the service.
    uninstall
    Uninstall the service.

Actually deploying xxeservice

Out of the box, C:\xxe\web\bin\xxeservice.exe, whose configuration file is in C:\xxe\web\bin\xxeservice.xml, is not very useful. The <arguments> element found in this XML configuration file contains the same basic options as those found in C:\xxe\web\bin\xxeserver.bat.
<arguments>-Xss4m -Xmx2048m -Djava.awt.headless=true
-DXXE_ADDON_PATH="%XXE_ADDON_PATH%" -DXXE_PREFS_DIR="%XXE_PREFS_DIR%"
-classpath "%XXESRVCP%" com.xmlmind.xmleditsrv.server.StartServer
-index "%BASE%\..\webapp\index.html"</arguments>
With this configuration:
  • The HTML page containing the sample XML editor is http://localhost:18078/xxe/. Hence you'll have a secure context Opens in new window only if you run the web browser on the same computer as xxeservice.
  • In practice, the sample XML editor only lets you edit local files. By default, no matter which user account was used to start xxeservice, access to remote files is limited to the “home directory” of LocalSystem, the system account used by the Windows service manager.
The <arguments> element which follows contains more useful options(1):
<arguments>-Xss4m -Xmx2048m -Djava.awt.headless=true
-DXXE_ADDON_PATH="%XXE_ADDON_PATH%" -DXXE_PREFS_DIR="%XXE_PREFS_DIR%"
-classpath "%XXESRVCP%" com.xmlmind.xmleditsrv.server.StartServer 
-loglevel INFO -logserver "%BASE%\..\var\srv" 
-keystore "%BASE%\..\etc\cert_192_168_1_26.pfx" -storepass changeit -keypass changeit
-faccess "%BASE%\..\etc\remote_files_conf.json"
-index "%BASE%\..\webapp\index.html"</arguments>
  • Variable %BASE% is predefined by xxeservice and is substituted with the path of the directory containing xxeservice.exe (which is C:\xxe\web\bin\ in this example).
    Remember that xxeservice.exe is just a renamed WinSW.exe, therefore more information about the <arguments> element, environment variables, etc, is found in XML configuration file Opens in new window.
  • By default, the value of option -loglevel is "WARN,WARN", meaning just log warnings and errors. Here, with "INFO" (or equivalently "INFO,WARN") we want xxeserver to be a little more verbose.
  • Option "-logserver %BASE%\..\var\srv" creates log files related to xxeserver as a WebSocket server in directory %BASE%\..\var\srv\ (which will be created if it does not already exist).
  • Options "-keystore %BASE%\..\etc\cert_192_168_1_26.pfx -storepass changeit -keypass changeit" let you specify which SSL certificate to use.
    Any option used to specify an SSL certificate will cause xxeserver to establish secure connections. Because option -port has not been explicitly used, xxeserver URLs will be wss://192.168.1.26:18079/xxe/ws and https://192.168.1.26:18079/xxe/.
  • Option "-faccess %BASE%\..\etc\remote_files_conf.json" points to a JSON configuration file specifying which remote files may be accessed by xxeserver client (which is the sample XML Editor in this example). In this example, remote_files_conf.json contains just a single line letting the sample XML Editor access any file found in C:\work. 
    [ { "label": "Work", "uri": "file:/C:/work" } ]
If you don't have an actual SSL certificate, option -selfsign lets you quickly generate a self-signed one.
<arguments>-Xss4m -Xmx2048m -Djava.awt.headless=true
-DXXE_ADDON_PATH="%XXE_ADDON_PATH%" -DXXE_PREFS_DIR="%XXE_PREFS_DIR%"
-classpath "%XXESRVCP%" com.xmlmind.xmleditsrv.server.StartServer 
-loglevel INFO -logserver "%BASE%\..\var\srv" 
-selfsign "CN=192.168.1.26" "%BASE%\..\etc\selfsign192_168_1_26.cert" 
-faccess "%BASE%\..\etc\remote_files_conf.json"
-index "%BASE%\..\webapp\index.html"</arguments>
Of course, with a self-signed SSL certificate, all web browsers will report a security issue.

Figure 5-4. Microsoft Edge reporting a security issue related to an SSL certificate

edge_cert_warning.png
The user of the web browser will have to click Advanced and then "Continue to xxeserver_address (unsafe)" to be able to load the HTML page containing xxeserver client (which is the sample XML Editor in this example). Generally this confirmation must be made just once, the first time you'll load the HTML page containing the client. After that, the web browser will store your self-signed SSL certificate as a “security exception”.

Figure 5-5. Microsoft Edge letting you accept the self-signed SSL certificate

edge_cert_proceed.png
 (1) You'll have to edit C:\xxe\web\bin\xxeservice.xml using a text or XML editor in order to change the <arguments> element.
Previous page Part II, Chapter 5, Section 1. Starting xxeserver on Linux or on macOS Part II, Chapter 5, Section 2. Starting xxeserver on Windows (10 / 25)   Table of Contents   Index Part II, Chapter 6. Integrating an XML editor into your web application Next page