velocity-config Command

Enables you to configure Watson Explorer Engine's embedded web server, including enabling whether the web server is started automatically as part of the velocity-startup command.

Velocity Config Command

velocity-config Enables you to configure the Watson Explorer Engine embedded web server, including enabling whether the web server is started automatically as part of the velocity-startup command.

Synopsis

velocity-config
    [-h|-help]
    [-installation-dir /path/to/engine/installation]
    [-quiet]
    [name=value]

Description

The velocity-config command is located in the bin subdirectory of a Watson Explorer Engine installation. This command enables you to display and set configuration information for Watson Explorer Engine's embedded web server by specifying name=value pairs on the command-line. This configuration information is stored in the file data/velocity-config.xml. This file will only exist if you have modified the configuration of the embedded web server. If the file does not exist, the default configuration values (listed later in this section) are used.

Executing the velocity-config command with no options displays the configuration options that are available for the embedded web server and their current values. The command and its output will look something like the following (which shows the default values for all of these options):

$ velocity-config
  global/admin-email                admin@localhost
  global/admin-url                  http://HOSTNAME-OR-IP/vivisimo/cgi-bin/admin
  global/api-url                    <unset>
  global/group                      <unset>
  global/password                   <unset>
  global/user                       <unset>
  HTTPauth                          password:
  HTTPauth                          user:
  webserver/base-url                /vivisimo/
  webserver/debug                   false
  webserver/host                    HOSTNAME-OR-IP
  webserver/is-enabled              false
  webserver/is-ssl-enabled          false
  webserver/port                    9080
  webserver/service-name            EngineWebServer
  webserver/ssl-certificate         <unset>
  webserver/ssl-certificate-key     <unset>

Note: On Microsoft Windows systems, the velocity-config command does not display the global/group option. On Linux systems, this command does not display the global/password and webserver/service-name options. See the description of these options later in this section for more information about their use and possible values.

As you can see from this example, the velocity-config command enables you to set two classes of configuration options: global values, which will affect the web server but which are intended to be used by other Watson Explorer Engine components, and webserver values, which only affect the configuration of the embedded web server. To set any of these values, specify the name of the option that you want to set and the value that you want to set it to, separated by an equals sign ('='). For example, to set the port that the webserver uses to port 10025, you would execute the command velocity-config webserver/port=10025. This command and its output would look like the following:

$ velocity-config webserver/port=10025
webserver/port  10025
Configuration saved...

The velocity-config command does not validate the values of any parameters that you set. For example, port numbers must be less than 65536, but are not checked when you set them.

Note: The global values that you can configure using the velocity-config command are currently only used by the Watson Explorer Engine embedded web server.

On Microsoft Windows systems, the velocity-config command has the .exe file extension.

Options

-h|-help: Displays a usage message and exits without performing any other actions.
-installation-dir/path/to/engine/installation: Enables you to specify the location of the Watson Explorer Engine installation that contains the web server which you want to configure. If no installation directory is specified, the velocity-config command assumes that the webserver directory and binaries are located in the Watson Explorer Engine installation directory which is the parent of the directory in which the velocity-config application is located.
-quiet: Suppresses normal output and warnings. Errors will still be displayed.

Configuration Items

The following list shows the configuration items for which values can be specified using the velocity-config command:

Important: If you are using Watson Explorer Engine's embedded web server, you must restart it after changing any of the configuration items supported by the velocity-config command.

global/admin-email: The email address shown by the webserver when an error is displayed. The default value of this configuration option is admin@localhost.
global/admin-url: The URL that should be used to contact the Watson Explorer Engine administration tool using the embedded web server. This value cannot be set manually - it is constructed internally using the webserver/base-url and webserver/host configuration options.
global/api-url: The URL that should be used to execute Watson Explorer Engine startup, shutdown, and API commands. The default value for this configuration option is <unset>. When this value is not set:
- If Watson Explorer Engine's embedded web server is not running, Watson Explorer Engine will attempt to derive this URL from localhost, the default port number for the web server, the virtual directory (base-url) that is specified in the Watson Explorer Engine installation's vivisimo.conf file, and the cgi-bin subdirectory.
- If Watson Explorer Engine's embedded web server is running, Watson Explorer Engine will use the URL that is displayed as part of the output of the velocity-webserver info command. This URL is derived from the hostname for the current system (if available), the port number specified in the webserver/port option, the virtual directory (base-url) that is specified in the installation's vivisimo.conf file, and the cgi-bin subdirectory.
This option is provided for use when Watson Explorer Engine applications are not installed in their default location, and therefore cannot be accessed through the default URL.
global/group: The name of the group that the web server should run as. On Linux systems, you must set both this configuration option and the global/user configuration option in order to start Watson Explorer Engine's embedded web server as the root user. This option is not used on Microsoft Windows systems. The default value of this configuration option is <unset>, indicating that no value has been set for this option yet. When this value is not set, the webserver will attempt to run as the group that is associated with the user who starts the webserver.
global/password: The password associated with the user that the web server should run as (which was specified by the global/user configuration option). The actual text value of the password is shown as a sequence of asterisks for security purposes, and is stored internally in a secure fashion. This option is only used on Microsoft Windows systems. The default value of this configuration option is <unset>, indicating that no value has been set for this option yet.
global/user: The name of the user that the embedded web server should run as.
On Linux systems, the embedded web server cannot run as the root user, but is typically started by a system script that is executed by the root user. You must therefore set both the global/user and global/group configuration options in order to identify the user and group identity that the root user will use to start and run the embedded web server. The specified user must be a member of the group specified by the global/group configuration option.
Note: Attempting to set global/user to the root user will display error messages, as in the following example:
```
# velocity-config global/user=root
ERROR:  The value for 'global/user' is invalid:
    Running Watson Explorer Engine as root is insecure and not allowed
      (ID: CLI_INVALID_CONFIG_VALUE_ERROR)

WARNING:  No changes were made to the stored configuration.
      (ID: CLI_NO_CONFIG_CHANGES_WARNING)
```
On Microsoft Windows systems, you must set both the global/user configuration option and the global/password option in order to start Watson Explorer Engine's embedded web server as a specified user. Some Windows installations may require that you specify the fully-qualified user name (DOMAIN\user) in order to correctly authenticate as a specified user.

The default value of this configuration option is <unset>, indicating that no value has been set for this option yet. When this value is not set on Linux systems, the webserver will attempt to run as the user who starts the webserver.
webserver/base-url: The base part of the admin and query-meta URLs. This configuration option is listed for convenience only, and cannot be set by the velocity-config command. It can only be set by editing the vivisimo.conf configuration file. The default value of this option is /vivisimo/. This option must begin with a '/' symbol, or attempting to access Watson Explorer Engine will result in an error.
webserver/debug: Whether the embedded webserver should start in debug mode (true) or not. When in debug mode, access logs and more descriptive error messages are recorded by the embedded webserver. The default value of this configuration option is false.
webserver/host: The host name or IP address of the system on which the embedded Watson Explorer Engine web server is running.
webserver/is-enabled: Whether the embedded web server is enabled (true) or not (false). If this variable is set to true and the embedded web server has not been removed from your Watson Explorer Engine installation, executing the velocity-startup command will automatically start the embedded web server. The default value of this configuration option is false.
webserver/is-ssl-enabled: Whether the embedded web server uses the Secure Socket Layer (SSL), now known as Transport Layer Security (TLS), for secure communication and data integrity verification. If this variable is set to true, you must also provide both an SSL certificate and key. The default value of this configuration option is false.
webserver/port: The port on which the embedded web server listens for data. The default value of this configuration option is 9080.
webserver/service-name: (Microsoft Windows only) The name of the Windows Service that is associated with Watson Explorer Engine. The default value of this option is EngineWebServer, which is a service that is created by Watson Explorer Engine.
webserver/ssl-certificate: The SSL certificate for the embedded web server. To provide a certificate, save it to a file and specify the name of the file, preceded by an '@' sign, as the value for this configuration option. As an example, the following command would set the SSL certificate for an embedded Watson Explorer Engine web server to the contents of the file corporate.crt:
```
velocity-config webserver/ssl-certificate=@corporate.crt
```
You can specify any file name as long as it contains the SSL certificate that you want to use. The default value of this configuration option is <unset>, indicating that no value has been set for this option yet.
webserver/ssl-certificate-key: the key for the SSL certificate associated with the embedded web server. To provide a key, save it to a file and specify the name of the file, preceded by an '@' sign, as the value for this configuration option. As an example, the following command would set the SSL certificate key for an embedded Watson Explorer Engine web server to the contents of the file corporate.key:
```
velocity-config webserver/ssl-certificate-key=@corporate.key
```
You can specify any file name as long as it contains a valid key for the SSL certificate that you are using. The default value of this configuration option is <unset>, indicating that no value has been set for this option yet.

Messages

See the Watson Explorer Engine Message Reference Manual for detailed information about any other messages that you may receive from the velocity-config command.

Exit Status

Exits with status 0 when the command is successful.

Note: On Linux systems, exit codes above 127 are returned by the shell. Please consult the documentation for the shell that you are using for more information.