Chapter 7. xxeserver command-line options Previous topic Parent topic Child topic Next topic

xxeserver, a WebSocket server, is the backend of XMLmind XML Editor Web Edition (XXEW). Its client is custom HTML element <xxe-client>.

xxeserver [Advanced option]* [Server option]*

Advanced options

These options may be used to add, replace or modify some user preferences.
Here the term user refers to the user who started xxeserver, not to the user who is using <xxe-client>.
XMLmind XML Editor user preferences are documented in XMLmind XML Editor - Online Help, Preference keys Opens in new window. Most user preferences do not apply to the Web Edition (XXEW). Examples: displayScaling, useNativeFileChooser.
-putprefs property_file
Similar to -putpref except that several key/value pairs may be read from specified property file..
-putpref key value
Adds or replace preference specified by key/value to the set of the user's preferences.
-delpref key
Removes preference specified by key from the set of the user's preferences..

Server options

-index file
Welcome file. Default: XXE_INSTALL_DIR/web/webapp/index.html, XXE_INSTALL_DIR being the directory where XMLmind XML Editor Web Edition (XXEW for short) has been installed. This file contains the sample XML editor application included in XXEW distribution.
This option implicitly sets the document root of xxeserver as an HTTP server. For example, "-index C:\temp\myapp.html" sets the document root to "C:\temp\". Therefore any file outside "C:\temp\" cannot be accessed using an "http://" URI.
This also implies that all <xxe-client> code (xxeclient.js, xxeclient.css, etc) must be found somewhere inside "C:\temp\" in order to be accessed by xxeserver.
-port port
Port to be used by the server. Default: 18079 if HTTPS, 18078 otherwise. See option -keystore below.
-keystore file
Keystore location. No default. Implies HTTP, not HTTPS.
-storetype type
Type of the keystore. Default: pkcs12 (a .pfx file for example).
-storepass password
Password for the keystore. No default.
-keypass password
Password for the private key. No default.
-certalias alias
Alias of the keystore entry. No default.
-selfsign dname cert_file
If cert_file does not already exist, use specified distinguished name dname to create a self-signed certificate in this file(1). Then use newly created or existing cert_file to expose only secure connections to clients. Ignored if option -keystore is used. No default.
The syntax of distinguished names (dname) is:
  • cName - IP address or fully qualified name of server host
  • orgUnit - department or division name, e.g., 'Purchasing'
  • org - large organization name, e.g., 'ABCSystems\, Inc.' (Notice the '\' used to protect the ','.)
  • city - city name, e.g., 'Palo Alto'
  • state - state or province name, e.g., 'California'
  • countryCode - two-letter country code, e.g., 'CH'
Each field must appear in the above order but it is not necessary to specify all fields. Examples:
CN=,OU=Dev tests,O=ACME Corp.,O=ACME Corp.,L=San Diego,S=California,C=US
If dname is "auto", then cert_file may also optionally contain substring "auto". In dname, "auto" is replaced by "CN=IPv4_ADDRESS_OF_THIS_COMPUTER" and in cert_file, "auto" is replaced by "selfsignIPv4_ADDRESS_OF_THIS_COMPUTER.pfx".
This spares you the effort of determining the IPv4 address of the computer running xxeserver, which is handy in the case of a quick test. Example, if the IPv4 address of the computer is then "-selfsign auto ..\etc\auto" is equivalent to "-selfsign CN= ..\etc\selfsign192.168.1.26.pfx".
-loglevel level[,level]?
Set logging level to ALL, TRACE, DEBUG, INFO, WARN, ERROR or OFF. Second, optional, level applies to the embedded Jetty Opens in new window server. Default: WARN,WARN.
-logrequests dir
Request logs will be created in this directory. Default: requests not logged.
-logserver dir
Server logs will be created in this directory. Default: not logged, messages are printed on the console.
-pid pid_out_file
Write xxeserver process ID to specified file. Fails if specified file already exists. No default.
Useful to stop xxeserver by executing a command equivalent to the Linux example below:
kill -SIGTERM `cat pid_out_file`
-faccess config_file|-|~|+|dir_list
Specifies which directories may be accessed by the client.
  • config_file is JSON configuration file specifying which directories may be accessed by the client. JSON configuration files are documented in Remote file access.
  • '-' may be used to specify: no file whatsoever.
  • '~' may be used to specify: any file found in the home directory of the user running xxeserver. Default value.
  • '+' may be used to specify: any file on this computer.
  • dir_list is a list of absolute or relative directory paths separated by ";". Append ":ro" to path to make directory read-only. Append "=label" to path to give the directory a label. Example: "/usr/local/doc:ro;/usr/share/doc:ro=Ref;/home/jjc;/opt/doc=Repo".
-maxeditors integer
Maximum number of active XML editors. Default: 25.
-recoverdocgracetime seconds
Minimum amount of time (in seconds) during which an XML editor may recover its opened document. Default: 300 (5 minutes).

Remote file access

xxeserver, the XML editor backend, may be configured to let <xxe-client>, the XML editor frontend, access files belonging to its files system. These are called remote files as opposed to local files which are found in the file system of the computer running the web browser.
The remote file access is specified by the means of a valid JSON configuration file which is passed to xxeserver using command-line option -faccess. The syntax of this JSON configuration file is:
    object [ , object ]*

object = {

"label": label_string ,
"uri": uri_string ,

"readonly": true|false ,

"prompt": prompt_string ,
"scheme": scheme_string ,
"username": username_string ,
"password": password_string

A JSON configuration file contains an array of objects. Each JSON object specifies the property of a remote file root. <xxe-client> may access any file contained directly or indirectly in a remote file root.
JSON object properties are:
Required. This label is displayed by the Remote File Chooser. See example below.
Required. The URI of the remote file root. Expected to be an absolute, hierarchical URI ending with '/'. May be not only a "file:///" URI but also an "http://", "https://" or "ftp://" URI.
The URI of the remote file root may reference client properties. These properties are passed to xxeserver by the means of the @clientproperties attribute of <xxe-client> or <xxe-app>See example below.
Optional. Specifies whether the remote file root is read-only or read-write. Read-only means that the user of the XML editor can open files found there but when modified, will have to save them to a different, read-write, remote file root.
Optional. String used to prompt the user for her/his credentials in order to access a remote file root requiring user authentication. Rarely used.
Optional. Authentication scheme used to access a remote file root requiring user authentication. Example: "BASIC", "DIGEST".
Always use pseudo-scheme "FTP LOGIN" when a remote file root has an "ftp://" URI.
Optional. Username used to access a remote file root requiring user authentication.
Optional. Password used to access a remote file root requiring user authentication.
    { "label": "Home", "uri": "file:///home/~(user)/" },
    { "label": "Source Code", "uri": "file:///usr/local/src/",
      "readonly": true },
    { "label": "Documents", "uri": "",
      "username": "~(user)", "password": "~(DAV.password)",
      "scheme": "DIGEST" },

    { "label": "Backup", "uri": "",
      "username": "admin", "password": "changeit",
      "scheme": "FTP LOGIN" }
About above example:
  • Variable references ~(user) and ~(DAV.password) are substituted with their values. These are client properties which are passed to xxeserver by the means of the @clientproperties attribute of <xxe-client> or <xxe-app>. Example:
    <xxe-client clientproperties="user=john;group=reviewers\u003Bauthors;DAV.password=changeit">
  • The "Source Code" remote file root is read-only.
  • The "Documents" remote file root requires WebDAV virtual drive plug-in to have been installed in XXEW. The "Backup" remote file root requires FTP virtual drive plug-in to have been installed in XXEW.
  • Labels "Home", "Source Code", "Documents", "Backup", are rendered by the Remote File Chooser as follows:

Remote file permissions

In the above example, the remote file root labeled "Home" is mapped to file:///home/~(user)/. This means that when <xxe-client> has been “personalized” with attribute @clientproperties="user=john", xxeserver will access all files found in file:///home/john/. With @clientproperties="user=jane", this will be file:///home/jane/, with @clientproperties="user=jack", this will be file:///home/jack/, etc.
Let's suppose xxeserver was started on the server by user U belonging to group G, this implies that:
  • User U/group G must have sufficient permissions to read and write any file found in file:///home/john/, file:///home/jane/, file:///home/jack/, etc.
  • All the files created by xxeserver in file:///home/~(user)/ will belong to user U/group G and not to user john, jane or jack. So what if user john, jane or jack wants to read and/or modify such files using tools other than XXEW?
Solving these problems is deemed feasible but depends on the operating system being used to run xxeserver and is out of the scope of this document.
On Linux/macOS, a simple solution is to make all users U, john, jane, jack, etc, belong to the same group G (e.g. staff) and to have all the members of this group have an umask Opens in new window equal to u=rwx,g=rwx,o=rx.

 (1) If needed to, the parent directories of this file are automatically created too.