Administrator

Relay Server Outbound Enabler Command (rsoe2) Reference

The rsoe2 command opens outbound connections from the Relay Server Outbound Enabler (RSOE) to the Relay Server.

rsoe2 [ <option> ]+
rsoe2 @{ <filename> | <environment-variable> } ...

Parameters

  • Options

    The following options can be used with the Outbound Enabler. Options that have defaults are optional. At a minimum, the Outbound Enabler needs to supply the connection string for the Relay Server (-cr), the farm (-f) and server (-id) names. If a security token is configured, it must also be specified (-t).

    rsoe2 options Description
    @ <data>

    Reads options from the specified environment variable or configuration file. To protect passwords or other information in the configuration file, you can use the File Hiding utility (dbfhide) to encrypt the contents of the configuration file.

    -cr "<connection-string>"

    Specifies the Relay Server connection string. The format of the Relay Server connection string is a semicolon separated list of keyword=value pairs. The keyword-value pairs consist of the following:

    • host

      IP address or hostname of the Relay Server. The default is localhost.

    • port

      The port that the Relay Server is listening on. This is required.

    • http_userid

      Userid for authentication. Optional. Consult your web server (or proxy) documentation to determine how to set up HTTP authentication.

    • http_password

      Password for authentication. Optional. Consult your web server (or proxy) documentation to determine how to set up HTTP authentication.

    • http_proxy_userid

      Userid for proxy authentication. Optional. Consult your web server (or proxy) documentation to determine how to set up HTTP authentication.

    • http_proxy_password

      Password for proxy authentication. Optional. Consult your web server (or proxy) documentation to determine how to set up HTTP authentication.

    • proxy_host

      The host name or IP address of the proxy server. Optional.

    • proxy_port

      The port number of the proxy server. Optional.

    • url_suffix

      URL path to the server extension of the Relay Server. Required.

      By default, the RSOE requires the url_suffix to be specified.

    • https

      0 - HTTP (default)

      1 - HTTPS

      For https=1, the following options can also be specified:

      • certificate_name

        Common name field of the certificate.

      • certificate_company

        Organization name field of the certificate.

      • certificate_unit

        Organization unit field of the certificate.

      • identity

        Provides the credentials to establish mutually authenticated TLS between the Outbound Enabler and the backend server. Mutual authentication is required for the backend server.

      • identity_password

        Provides the credentials to establish mutually authenticated TLS between the Outbound Enabler and the backend server. Mutual authentication is required for the backend server.

      • fips

        Choose whether to use FIPS-certified encryption implementations for TLS encryption and end-to-end encryption.

      • trusted_certificates

        A file containing a list of trusted root certificates.

        To verify the backend server, and only the backend server, set this property to backend_server_public_cert_filename.

        trusted_certificates=backend_server_public_cert_filename

        For Windows, if trusted_certificates is not set, the operating system certificate store is used.

    -cs "<connection-string>"

    Specifies the backend server connection string. The format of the connection string is a semicolon separated list of name-value pairs. The name-value pairs consist of the following:

    • host

      IP address or hostname of the backend server. The default is localhost.

    • port

      The port the backend server is listening on. This is required. The default is 0.

    • https

      0 - HTTP (default)

      1 - HTTPS

      By default, MobiLink starts up the TCPIP communication protocol. When starting MobiLink for use with the RSOE, be sure to start the communication protocol required by your RSOE configuration. For example, if you specify HTTPS as the backend security, then MobiLink must be started with HTTPS.

      When the https=1 parameter is included in the -cs option, the default port changes to 443.

      For https=1, the following options can also be specified:

      • identity

        The path and file name of the identity file that is to be used for server authentication. Provides the credentials to establish mutually authenticated TLS between the Outbound Enabler and the backend server. Mutual authentication is required for the backend server.

      • identity_password

        An optional parameter that specifies a password for the identity file. When this option is specified, the identity option must also be specified. Provides the credentials to establish mutually authenticated TLS between the Outbound Enabler and the backend server. Mutual authentication is required for the backend server.

      • trusted_certificates

        A file containing a list of trusted root certificates.

        To verify the backend server, and only the backend server, set this property to backend_server_public_cert_filename:

        trusted_certificates=backend_server_public_cert_filename

        For Windows, if trusted_certificates is not set, the operating system certificate store is used.

    • status_url

      Enables backend status requests. This option can be set in the RSOE configuration file (for example): -cs "host=localhost;port=80;status_url=/getstatus/". The frequency of the backend server liveness ping is set using the -d option.

      If status_url is specified, the RSOE sends a simple HTTP GET request as follows: GET /<<your-status-url>> HTTP/1.1\r\n Host: localhost:80\r\n User-Agent: IAS_OE_BE_Status\r\n Connection: close\r\n \r\n. The RSOE parses the backend server's HTTP response and looks for AVAILABLE =<accept-value> in the BODY of the HTTP response, where <accept-value> is one of: TRUE, FALSE, T, F, YES, NO, Y, N, ON, OFF, 1, or 0. If the RSOE receives AVAILABLE=FALSE|F|NO|N|OFF|0, it assumes that the backend server is not willing to accept more client requests and terminates its channels to the Relay Server. If the RSOE receives AVAILABLE=TRUE|T|YES|Y|ON|1, it re-establishes its channels with the Relay Server and resumes sending client requests to the backend server.

    -d <seconds>

    Sets the frequency of the backend server liveness ping and backend server status request. The default is 5 seconds.

    -dl

    Use this option to display log messages in the Relay Server Outbound Enabler console. By default, log messages are not displayed for verbosity levels 1 and 2.

    -f <farm>

    Specifies the name of the farm that the backend server belongs to.

    -id <id>

    Specifies the name assigned to the backend server.

    -jsh <number>

    Specifies the maximum number of junctions in the idle junction pool. The total number of junctions is allocated evenly across the number of Relay Servers in the farm. The default value is 200.

    -jsl <number>

    Specifies the minimum number of junctions in the idle junction pool. The total number of junctions is allocated evenly across the number of Relay Servers in the farm. The default value is 10.

    -jl <number>

    Specifies the maximum number of junctions (the sum of active and idle junctions). The total number of active and idle junctions is allocated evenly across the number of Relay Servers in the farm. This setting is overriden by the setting for max_junction in the Backend Server section of the Relay Server configuration file. The default value is 1000.

    -o <file>

    Specifies the file to log output messages to.

    -oq

    Prevents the appearance of the error window when a startup error occurs.

    -os <size>

    Sets the maximum size of the message log files. The minimum size limit is 10 KB.

    -ot <file>

    Truncates the specified log file and logs messages to it.

    -q

    Run with a minimized window on startup.

    -qc

    Shuts down the window on completion.

    -s

    Stops the Outbound Enabler.

    -t <token>

    Sets the security token to be passed to the Relay Server.

    -uc

    Starts rsoe2 in shell mode. This is the default. Applies to Unix and Mac OS X.

    Only specify one of -uc, -ui, -um, or -ux. When you specify -uc, this starts the RSOE in the same manner as previous releases of the software.

    -ud

    Instructs rsoe2 to run as a daemon. This option applies to Unix platforms only.

    -ui

    Starts rsoe2 in shell mode if a usable display is not available. This option is for Linux with X window server support.

    When -ui is specified, the server attempts to find a usable display. If it cannot find one, for example because the X window server isn't running, then rsoe2 starts in shell mode.

    -ux

    Opens the RSOE messages window where messages are displayed on Linux.

    On Windows, the RSOE messages window appears automatically.

    When -ux is specified, the RSOE must be able to find a usable display. If it cannot find one, for example because the DISPLAY environment variable is not set or because the X window server is not running, the RSOE fails to start.

    To run the RSOE messages window in quiet mode, use -q.

    -v <level>

    Sets the verbosity level to use for logging. The <level> can be 0, 1, 2, or higher (higher levels are used primarily for Technical Support):

    • 0

      Log errors only. Use this logging level for deployment.

    • 1

      Session level logging. This is a higher level view of a synchronization session.

    • 2

      Request logging. Provides a more detailed view of HTTP requests.

    • 3 or higher

      Detailed logging. Used primarily for Technical Support.

    Levels 1 and 2 are only written to the message log file and are not displayed. To have all log messages displayed, use the -dl option.