Robust Configuration

The index of this documentation is at Iains Documentation Skunkworks.

Work In Progress: This is officially a draft, based on a reading of the source code that is referenced during the boot up and initialization of the Robust server.

Current progress is documenting the service connectors in the [ServiceList] section. Each connector will likely have its own area in this page. Any places where it expects properties in other sections will be noted.

Current service connector: InventoryInConnector is being documented now.

This is the configuration for the Robust server.

By default, this configuration is in a file in the pwd, with the same base name as the executable. The executable file's extension (if any) is replaced with ini. So, if you haven't changed the name of the executable, it is Robust.ini in the pwd.

The --inifile (short form -i) command line switch sets a different source. Relative file paths are relative to the pwd. If a file is specified, it is exptected to be in the INI format. If a URL is specified, the data is expected to be an XML stream.

The Startup|ConfigDirectory property, if set to a relative path, is relative to the pwd.

[Startup] Mandatory section.

A few properties are related to command line switches. If the command line switch is used, it overrides these properties. If the command line switch is not used, these properties are used. If a property is missing, its default value is used instead.

• prompt (string) The prompt displayed on the command console.
  • Overridden by the --prompt (short form -p) command line parameter.
  • Default: If not specified here or on the command line, the default is "R.O.B.U.S.T."
• console (string) The console type
  • Overridden by the --console (short form -c) command line parameter.
  • local A console with colors, cursor control and editing, and logging. On the controlling terminal.
  • basic A console with no frills. Backspace works, and that's it. On the controlling terminal.
  • rest A network console accessible through http(s). See the console properties in the [Network] section.
  • mock For testing only. Do not use. Remember what happened with the original Grim Fandango if you ejected the CD at the wrong time? Ya. Don't. Just... don't.
  • Default: local.
• logfile
  • Overridden by the --logfile (short form -l) command line parameter
• logconfig (string) The XML configuration file for Log4Net. Default: "Robust.dll.config"

Local Console properties:

The persistent console history file allows Robust to remember previously entered commands across runs. Disabling it means every run is a fresh start for command history.

• ConsoleHistoryFileEnabled (boolean) Enables saving command history to a file. Default: false.
  • ConsoleHistoryFile (string) The file for the console history. Default: OpenSimConsoleHistory.txt
    • This can be a relative path off the pwd or an absolute path.
  • ConsoleHistoryFileLines (integer) The number of lines to truncate the history file to on boot. Default: 100.
    • When the pre-existing history file is loaded during boot, the first lines are removed to get the file down to this many lines.
  • ConsoleHistoryTimeStamp (boolean) Whether to include timestamps in the history file. Default: false.

Other properties:

• ConfigDirectory (string)
  • The path for the modular ini directory. If it is a relative path, it is relative to the pwd.
  • The only user of this directory seems to be the Gloebit money module.
  • The example robust.ini sets it to "robust-include"
  • Default: If not specified, the default is "." which is the pwd.
• PIDFile (string) The pathname of a PID file to create on startup. This path, if relative, is relative to the pwd.
  • Default: Don't open a PID file.

Some random networking properties:

• DnsTimeout (integer)
  • The length of time the system considers a DNS resolution to be valid, in milliseconds.
  • Default: 30000 (which is 30 seconds).
• NoVerifyCertChain (boolean)
  • If true, the HTTP handlers do not check for remote certificate chain errors on outgoing TLS connections.
  • Default: false
• NoVerifyCertHostname (boolean)
  • If true, the HTTP handlers do not check for remote certificate name mismatch errors on outgoing TLS connections.
  • Default: false

Self-signed server certificate:

• EnableRobustSelfsignedCertSupport (boolean)
  • If this is false, there is no support for self-signed server certificates, and the rest of these properties are ignored.
  • Default: false.
• RobustCertFileName (string)
  • This is the base file name for the certificate. It lives in ./SSL/ssl/filename.p12 where filename is this property value.
  • If this is not specified it defaults to Robust when creating a new cert file.
  • Note: When determining whether to create/recreate a cert, this does not default.
• RobustCertRenewOnStartup (boolean)
  • If this is true, then a new cert file is created during server startup.
  • If this is false, and there is no existing cert file, a new one is created.
  • If this is false, and there is an existing cert file, the following properties are ignored.
• RobustCertHostName (string)
  • The hostname for the cert. This becomes the CN and the Subject Alternative Name DNS name.
  • Default: "localhost"
• RobustCertHostIp (string)
  • The IP address for the cert. This becomes the Subject Alternative Name IP address.
  • Default: "127.0.0.1"
• RobustCertPassword (string)
  • The password for accessing the private key part of the cert.
  • Default: The empty string.
  • Caution: You can let this default to the empty string, and the created cert files and private key file will be unencrypted. However... code that attempts to use the cert file refuses to accept an empty string as the password. So this property must be defined.

Plugin Loading properties:

• RegistryLocation (string)
  • This is the path to a directory. (TBD what it means -- passed to the PluginLoader).
  • Default: . (AKA the pwd).
• ServiceConnectors (string)
  • A string listing a set of Service Connectors. These are exactly the same as in the [ServiceList] section, separated by commas, spaces, newlines, carriage returns, or tabs. See that section for a description of what a service connector entry looks like.
  • These connector entries are put at the front of the connector list when the [ServiceList] section is processed. So they are loaded before any connectors listed in that section.
  • Default: the empty string.

[ServiceList]

This is a list of Service Connectors. The property names are ignored (but they must be there to satisfy the INI file or XML format requirements). The property values are the Service Connectors.

Service Connector grammar

Here is the specification of the Service Connector description:

property-value = [config-port "/"] connector
config-port = [config-name "@"] port-number
connector = dll-name-and-args [ ":" class-name]
dll-name-and-args = *(argument "@") dll-name

At the core of it all, we have a dll filename. Relative pathnames are relative to the pwd. This is the dotnet Assembly that is loaded.

The dll-name can optionally be preceded by a set of argument strings, separated by @ characters. These are extra arguments that get passed to the plugin's constructor method.

The dll (plus arguments) can optionally be followed by a : and a class name within the dotnet Assembly.

This whole mess can optionally be preceded by a / and a port number, and even more optionally, a config-name followed by a @.

An example:

SomeConfig@8002/arg1@arg2@Some.DotNet.Assembly.dll:ClassToLoad

But most connectors are simply port/dll:class.

How they're processed

These Service Connectors are processed in the order they appear in the configuration. If the port number is given, the service connector code is hooked up to the given TCP/UDP port on the main server. If not, it is hooked up to the main server's main port.

Technical Stuff

The dll-name is the name of a DLL file (assembly). This is mandatory. No pathnames! The code expects only one / and will not parse the connector string properly!

The class-name is the name of a class in the DLL. If not provided the server looks for the first class in the assembly that meets the criteria (below).

The port-name is a TCP/UDP port number. If not specified, the main server private port is used.

The config-name is passed as a parameter to the constructor for the chosen class. If not specified it is an empty string.

The argument values are also passed to the constructor.

Class criteria:

• The class must implement the IServiceConnector interface. The sub-interface ServiceConnector also works.
• There must be a constructor that takes the following arguments:
  • The full server configuration
  • The http server assigned to this connector
  • The config-name
  • Any arguments in the dll-name-and-args part of the connector string.

If no such constructor is found, the server tries again without the config-name parameter.

If no class successfully got loaded, no service connector is loaded, and an error is sent to the logfile.

The connectors

Here's a list from the Robust.ini.example file. The config sections used by these connectors will be after hrules in this page:

AssetServiceConnector = "${Const|PrivatePort}/OpenSim.Server.Handlers.dll:AssetServiceConnector"
InventoryInConnector = "${Const|PrivatePort}/OpenSim.Server.Handlers.dll:XInventoryInConnector"
GridServiceConnector = "${Const|PrivatePort}/OpenSim.Server.Handlers.dll:GridServiceConnector"
GridInfoServerInConnector = "${Const|PublicPort}/OpenSim.Server.Handlers.dll:GridInfoServerInConnector"
AuthenticationServiceConnector = "${Const|PrivatePort}/OpenSim.Server.Handlers.dll:AuthenticationServiceConnector"
OpenIdServerConnector = "${Const|PublicPort}/OpenSim.Server.Handlers.dll:OpenIdServerConnector"
AvatarServiceConnector = "${Const|PrivatePort}/OpenSim.Server.Handlers.dll:AvatarServiceConnector"
LLLoginServiceInConnector = "${Const|PublicPort}/OpenSim.Server.Handlers.dll:LLLoginServiceInConnector"
PresenceServiceConnector = "${Const|PrivatePort}/OpenSim.Server.Handlers.dll:PresenceServiceConnector"
UserAccountServiceConnector = "${Const|PrivatePort}/OpenSim.Server.Handlers.dll:UserAccountServiceConnector"
GridUserServiceConnector = "${Const|PrivatePort}/OpenSim.Server.Handlers.dll:GridUserServiceConnector"
AgentPreferencesServiceConnector = "${Const|PrivatePort}/OpenSim.Server.Handlers.dll:AgentPreferencesServiceConnector"
FriendsServiceConnector = "${Const|PrivatePort}/OpenSim.Server.Handlers.dll:FriendsServiceConnector"
MapAddServiceConnector = "${Const|PrivatePort}/OpenSim.Server.Handlers.dll:MapAddServiceConnector"
MapGetServiceConnector = "${Const|PublicPort}/OpenSim.Server.Handlers.dll:MapGetServiceConnector"
;; Uncomment this if you want experience tools to work
; ExperienceServiceConnector = "${Const|PrivatePort}/OpenSim.Server.Handlers.dll:ExperienceServiceConnector"
;; Uncomment this if you want offline IM to work
; OfflineIMServiceConnector = "${Const|PrivatePort}/OpenSim.Addons.OfflineIM.dll:OfflineIMServiceRobustConnector"
;; Uncomment this if you want Groups V2 to work
; GroupsServiceConnector = "${Const|PrivatePort}/OpenSim.Addons.Groups.dll:GroupsServiceRobustConnector"
;; Uncomment to provide bakes caching
; BakedTextureService = "${Const|PrivatePort}/OpenSim.Server.Handlers.dll:XBakesConnector"

;; Uncomment for UserProfiles see [UserProfilesService] to configure...
; UserProfilesServiceConnector = "${Const|PublicPort}/OpenSim.Server.Handlers.dll:UserProfilesConnector"

;; Uncomment if you want to have centralized estate data
; EstateDataService = "${Const|PrivatePort}/OpenSim.Server.Handlers.dll:EstateDataRobustConnector"

MuteListConnector = "${Const|PrivatePort}/OpenSim.Server.Handlers.dll:MuteListServiceConnector"

VoiceServiceConnector = "${Const|PrivatePort}/WebRtcVoice.dll:WebRtcVoiceServerConnector"

I took the liberty of removing FreeSwitch from the list. I tried getting that thing working, Bruce Almighty I tried. I had to hunt for multiple out-dated libraries with abandoned dependencies, and had no sweater at the end. It compiled, connected to Robust, and failed to produce sound. "Shaka, when the walls fell." Or, the more archaic "Napoleon at the bowling alley in Bill and Ted's Excellent Adventure."

At the other end, the much newer WebRtcVoice is current, and the voice mixing server it depends on, Janus Gateway, is also under active current development.

[Environment]

This section lists environment variables to be pulled in. During server startup, the variables are retrieved, and replace the values given here.

NOTE: If a property name here is not an environment variable, it is removed from the configuration! So a property called BLAH here is removed if there is no environment variable called BLAH set when the server boots up.

[Network] Mandatory section.

This specifies the network configuration of the main server http/https ports.

• port (unsigned intger) mandatory
  • This is the private port of the Robust server. It is installed as the primary http(s) server for the Robust instance.
• https_main (boolean) Default: false
  • If this is true, the port will use TLS, with the given certificate (see below).
• https_listener (boolean) Default: false
  • If this is true, a second port is opened for TLS use, if https_external is false.
  • https_port (unsigned integer) mandatory
    • This is the port to open for the second https port. Warning: it defaults to 0. This is a reserved port number in the TCP/IP protocol, and should not be used. In short, if you set https_port to true, you must set this to a proper non-zero TCP/IP port number.
  • https_external (boolean) Default: false
    • If this is set to true, then the https_port is created without TLS.
• If either https_main or https_listener is true, these properties are mandatory:
  • cert_path (string) (mandatory) is the path to the X509 certificate PKCS12/PFX file for this port.
  • cert_pass (string) (mandatory) is the password needed to decrypt the private key in the cert file.
• AllowllHTTPRequestIn (boolean)
  • Permit LSL/OSSL scripts to access endpoints on the private port using llHttpRequest().
  • This global setting can be overridden in individual services.
  • Default: false
• AuthType (string)
  • Sets the authentication type to use for authenticating incoming HTTP connections.
  • Two options are available: None and BasicHttpAuthentication.
  • This global setting can be overridden in individual services.
  • Default: None

Properties to do with the rest command console:

• ConsolePort (unsigned integer) The port the rest console listens on. Default: 0
  • If this is zero, then the console listens on the server's private port.
• ConsoleUser (string) The username to get into the rest console. Default: empty string.
• ConsolePass (string) The password to get into the rest console. Default: empty string.
• ConsoleAllowedOrigin (string) The value to put in the Access-Control-Allow-Origin HTTP response header. This appears mainly for JavaScript console UIs that use XmlHttpRequest or fetch to talk to the console, but that is unclear.

[Monitoring]

• ServerStatsEnabled (boolean) Set to true to enable server statistics
  • CPU stats are collected.
  • Default: false
  • NetworkInterfaceTypes (string) A comma separated list of network interface types to monitor statistics for.
    • Default: "Ethernet"
    • Note: Only IPv4 interface types are supported. All other interfaces are silently ignored.

[DatabaseService] Optional section

The default database connection setup. Each plugin that uses the database may have their own storage provider or connection string. If they don't, they fall back to the values in this section. For all, some database setup must exist.

• StorageProvider (string)
  • This is the DLL name for a storage provider. There are three main options:
    • OpenSim.Data.MySQL.dll for MySQL
    • OpenSim.Data.PGSQL.dll for Postgres
    • OpenSim.Data.SQLite.dll for SQLite
• ConnectionString (string)
  • This is the connection string to gain access to the database.
  • For Postgres, it would be of the general form Server=localhost;Database=opensim;User Id=opensim; password=***;
  • For MySQL, it would be of the general form Data Source=localhost;Database=opensim;User ID=opensim;Password=*****;Old Guids=true;SslMode=None;
  • Insert the machine the database server is on, the database name, the user credentials.

---

From the Asset Service Connector

The config-name is the section name, which defaults to [AssetService].

[AssetService] Mandatory section.

• LocalServiceModule (string) mandatory
  • This is the local service for asset management. There are two options in Robust.ini.example. Only one can be selected.
    • OpenSim.Services.AssetService.dll:AssetService
    • OpenSim.Services.FSAssetService.dll:FSAssetConnector
• AllowRemoteDelete (boolean)
  • If set to true, it is possible to delete assets through the HTTP endpoint. Which assets depends on the AllowRemoteDeleteAllTypes setting.
  • Default: false
• AllowRemoteDeleteAllTypes (boolean)
  • If set to true and AllowRemoteDelete is also true, all types of assets can be deleted through the HTTP endpoint. The example INI file says to set this only if you control all calls, and only for administrative purposes.
  • If set to false and AllowRemoteDelete is trye, only map tiles can be deleted through the HTTP endpoint.
  • Default: false
• RedirectURL (string)
  • Default: empty string
• AllowllHTTPRequestIn (boolean) See the note in the [Network] section.
• AuthType (string) See the note in the [Network] section.

Loading of default assets:

• AssetLoaderEnabled (boolean)
  • If true, default assets loading is enabled during boot.
  • Default: true
• DefaultAssetLoader (string) Optional
  • This is the loader for the default assets -- the assets that show up in the Library folder in your inventory.
  • If this is not specified, then default assets are not loaded into the DB during server bootup.
  • OpenSim.Framework.AssetLoader.Filesystem.dll is in the example ini file. It is the only loader at present.
• AssetLoaderArgs (string) Mandatory if DefaultAssetLoader is specified
  • This is the path to the root of the default asset set, relative to the pwd (unless an absolute path is given).
  • It points to a Nini XML configuration. There is a section for each asset set, and one property called file which holds the path to another Nini XML configuration listing all the assets for that set.
  • The value given in the example INI file is ./assets/AssetSets.xml

To override the default database connection settings (for both local service modules):

• StorageProvider (string)
  • If the Asset Service will be using a different database server type from the default.
• ConnectionString (string)
  • If the Asset Service is using a different db type, there needs to be a proper connection string.
  • Otherwise, if you want to use
    • a different server (eg different node in a cluster, etc)
    • a different database name
    • a different database user

Properties used by the FSAssetConnector local service module:

• SecondaryInstance (boolean)
  • Indicates whether the current server is the primary or a secondary instance of the FS Asset Service.
  • Default: false
• Realm (string)
  • The table in the backing database to use for storing asset metadata.
  • Default: fsassets
• DaysBetweenAccessTimeUpdates (number)
  • When assets are accessed, the access-time in the metadata is only updated every n days. If this is zero, the database is updated every access.
  • Default: 0
• FallbackService (string)
  • This can be OpenSim.Services.AssetService.dll:AssetService indicating the local service module as a fallback.
  • If an asset cannot be found for retrieval in the FS Asset store, it is retrieved from the fallback service module.
  • Default: no fallback service.
• SpoolDirectory (string)
  • The spool directory is the spool directory off of this.
  • Newly created assets have their data files stored here, and a separate thread periodically goes through the files and moves them to their final locations in the BaseDirectory.
  • Default: /tmp
• BaseDirectory (string) Mandatory
  • This is the directory for storage of asset data files. Relative to the pwd.
  • It is set to fsassets/data in the example INI file.
• UseOsgridFormat (boolean)
  • The directory structure under the BaseDirectory can be of two types: Regular and OSGrid. True means use the OSGrid structure.
  • In the OSGrid structure, there are two layers of directories named as follows: the first three characters of the hash, then the next three characters of the hash.
  • In the Regular structure, there are four layers of directories named as follows: the first two characters, the next two, then the next two, finally the next four.