Orbit 3DM Publisher Service

This page is a glossary and bundles technical information about the Orbit 3DM Publisher Service including Orbit Enterprise Orbit Service (EOS) and Internet Orbit Service (IOS) used for HTTP Web Service.

The “Enterprise Orbit Service” or shortened “EOS” is Orbit's core server technologies for central storage, management, and sharing of Reference GIS and 3DM Mapping, Reality Resources.
EOS enables corporate management of users, permissions, workspaces, and licenses. It is the backbone of Orbit 3DM Publisher.

Configuration to connect and load resources from supported cloud blob storages.

• File locations
  • Preferred: <Install Dir>/../Orbit 3DM Publisher Service Data/storage/amazon.store.<config.name>.ini
  • Legacy: <Install Dir>/program/config/amazon.store.<config.name>.ini
  • config.name: Orbit configuration name for the cloud storage. Free of choice, lower case, no special characters.
• Use the prefix am:/<config.name>/ in the resource file path to access the root folder of the AWS Bucket.

type amazon
access.key xxx
secret.key xxx
region.name xxx
bucket.name xxx
readonly true
cache true
cache.expire.time 7200.0
file.content.read.thread.count 12

• region.name: Amazon regional endpoint code, see https://docs.aws.amazon.com/general/latest/gr/rande.html

• Configure like Amazon S3 Bucket, see above.
• Add Storage provider service endpoint url to the Cloud Storage configuration file.
• For MinIO endpoints the property forcePathStyle needs to be set to true

endpoint.url https://play.min.io
forcePathStyle true

• File locations
  • Preferred: <Install Dir>/../Orbit 3DM Publisher Service Data/storage/azure.store.<config.name>.ini
  • Legacy: <Install Dir>/program/config/azure.store.<config.name>.ini
  • config.name: Orbit configuration name for the cloud storage. Free of choice, lower case, no special characters.
• Use the prefix az:/<config.name>/ in the resource file path to access the root folder of the Azure Container.

account.name xxx
account.key xxx
container.name xxx
readonly true
cache true
cache.expire.time 7200.0
file.content.read.thread.count 12

• File: <Install Dir>/program/config/minio.store.<config.name>.ini
  config.name: Orbit configuration name for the cloud storage. Free of choice, lowercase, no special characters.
• Jars: Additional jar files are needed to connect to the MinIO Storage.
  Download, unzip, and copy into <Install Dir>/program/software/lib.
• Java Options: Additional module --add-modules=kotlin.stdlib in the right place be loaded at starting the Publisher service.
  • Windows: <Install Dir>/program/bin/ServiceInstall.bat
    JAVA9_OPTIONS : ... ;'%INSTALL_DIR%/software/lib;--add-modules=kotlin.stdlib;--add-modules=core.toolx ...
  • Linux: <Install Dir>/program/bin/wrapper.conf
    # Java Additional Parameters : wrapper.java.additional.6=--add-modules=kotlin.stdlib
• Use the prefix mio:/<config.name>/ in the resource file path to access the root folder of the MinIO Container.

type minio
endpoint.url xxx
access.key xxx
secret.key xxx
bucket.name xxx
readonly false
cache true
cache.expire.time 7200.0
file.content.read.thread.count 12

As of the 25.3.0 release the connection to MinIO storage will be done by using the Amazon S3 configurations.

Follow these migration steps:

• rename each “minio.store.XXX.ini” file into “amazon.store.XXX.ini”
• edit each new “amazon.store.XXX.ini” file:
  1. change “type” from “minio” into “amazon”
  2. change/add “region.name” to be “aws-global”
  3. add “endpoint.url” to be “https://play.min.io”
  4. add “forcePathStyle” to be “true”

Each storage connection has settings for caching file content. This prevents reading from a slow connection for parts of files that have already been read before. Disable the cache if you always want to read live content.

1. cache is a boolean so either “true” or “false” (default is true)
2. cache.expire.time is a number in seconds to keep a cache entry alive (default is 3600 seconds)
3. file.content.read.thread.count is the number of concurrent connection threads to the storage (default is 10)

Global cache settings exist as well, they apply to all storage connections. The settings are defined in the global configuration file of the application.

1. file.content.cache.block.size is the number of bytes in a cache entry (default is 262144 or 256KB)
2. file.content.cache.block.count is the maximum number of cache entries (default is 0)
3. file.content.cache.mem.percent is the percentage of memory available for caching (default is 0)

If both the block count and mem percent are zero then the number of cache entries defaults to 400 (100MB total cache size). But the recommendation is to set the mem percent to 50 to allow room for normal operations in addition to caching.

Configuration to set Cross-origin for Publisher service.
More information about CORS concepts

• https://en.wikipedia.org/wiki/Cross-origin_resource_sharing
• https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS

When embedding and accessing the Publisher from a different domain (for example from an SDK integration), all browsers apply cross-origin resource sharing restrictions.

• File : <Install Dir>/program/config/server.ini
• Parameters:
  • http.cors.enabled: Enable CORS headers
  • http.cors.alloworigin: Value for the Cross-Domain-Allow-Origin header
  • http.cors.allowmethods: Value for the Cross-Domain-Allow-Methods header
  • http.cors.allowheaders: Value for the Cross-Domain-Allow-Headers header (Authorization, Content-Type, …)
  • http.cors.maxage: Value in seconds for the Cross-Domain-Max-Age header
  • http.cors.allowcredentials: Boolean value for the Cross-Domain-Allow-Credentials header

To enable cross-domain cookies, the SDK needs to get a specific startup option.
This may be needed for example when using Publisher with a load balancer that needs cookies to maintain session stickiness.

Example: Enable Cross-Domain with Cookies

Configuration to set URL to connect and download time-out.

• File : <Install Dir>/program/config/server.ini
• Parameters :
  • urldownloader.timeout.connect
  • urldownloader.timeout.read
• Value : Milliseconds as integer value
• Default Value : 60000

urldownloader.timeout.connect      120000
urldownloader.timeout.read         120000

Desktop Client-Server Communication

The Orbit toolkit is network-neutral. Connectivity requires an IP-resolve system (such as a DNS). The Data Orbit eXchange protocol or shortened “DOX” protocol is Orbit's proprietary communication protocol between the Orbit tiers.

DOX requires only 1 port to be accessible from the outside. Firewalls thus need only to open 1 port to allow remote access to an Orbit server system (in contradiction to standard Java RMI connectivity).
DOX is a compressed and binary way to do the communication between Orbit Client and Orbit Server in the most secure, simple, and fast way. It has no relation with HTTP or the alikes, but of course, runs over Tcp/Ip.
DOX does not influence any other protocol and cannot be hacked.

All Orbit Products are able to access remote EOS resources and instantly become client/server applications, providing access to corporate resources. Most Orbit products are available both in Standalone as in Client-Server.

The Orbit EOS service reads all resource requested by Orbit Clients and read & writes configurations as set by the EOS Console.
Consequently, Orbit EOS Service requires read access on all used resource files and read & write access to all Orbit setup and configuration files.

Special attention is required regarding file access permissions for the Operating System User running the EOS service.
Additional note on Windows, Mapped Network Drives are not available to Operating System Services, use of Uniform Naming Convention (UNC) is required.

When adding resources to EOS, using the Publisher Console ensure the EOS service has access to the added resources at all time.

Disk space or file access issues on EOS configuration files will result in corrupted configurations and software malfunction. Ensure there is enough disk space and all EOS configuration files are accessible at all times.

Orbit EOS Service account settings are applied at Service Install.
One can use the Operating System services management console to update the User Account or add User credentials into the Orbit service installation files.
Configuration update on the Service installation files requires the Orbit Service to be be stopped, removed, updated, re-installed, and restarted. Verify the update using the OS Services Management Console.

• <Install Dir>/program/bin64/ServiceInstall.bat

set SERVICE_USER=--ServiceUser=<Domain>\<UserName> --ServicePassword=<UserPassword>

The default configurations for all outgoing HTTP and HTTPS requests can be updated. However, we do advise using the default operating system proxy settings.

Proxy configurations are set at Service Install. Changing these configurations requires the Orbit Service to be stopped & removed, installed & restarted.

Only if required - Settings for proxy and firewall for Bentley Connexion Client and Bentley Licensing Tool in server mode https://bentleysystems.service-now.com/community?id=kb_article&sysparm_article=KB0018790

Add the following Java VM arguments into :

• Linux : <Install Dir>/program/bin/wrapper.conf > Java Additional Parameters
• Windows : <Install Dir>/program/bin/ServiceInstall.bat > JAVA_OPTIONS & Bentley Licencing Tool

Set system proxy settings

-Djava.net.useSystemProxies=true

Set other proxy settings
Below for https, for http replace “-Dhttps” by “-DHttp” :

-Dhttps.proxyHost=0.0.0.0
-Dhttps.proxyPort=0000
-Dhttps.proxyUser=xxx
-Dhttps.proxyPassword=xxx

When using a proxy that doesn't require user validation, parameters “proxyUser” and “proxyPassword” should not be added.

Example :

set JAVA_OPTIONS=-Djava.net.useSystemProxies=true;-Dhttps.proxyHost=0.0.0.0;-Dhttps.proxyPort=0000

Https example for Linux :

# Java Additional Parameters
wrapper.java.additional.1=-Xrs
wrapper.java.additional.2=-Djava.awt.headless=true
wrapper.java.additional.3=-Dhttps.proxyHost=0.0.0.0
wrapper.java.additional.4=-Dhttps.proxyPort=0000
wrapper.java.additional.5=-Dhttps.proxyUser=xxx
wrapper.java.additional.6=-Dhttps.proxyPassword=xxx

To redirect incoming HTTP traffic to the HTTPS web service.

1. Create a new folder http80 into <Install Dir>/program/services
2. Create a new file service.ini into the newly created folder <Install Dir>/program/services/http80
   Copy, paste and save the snippet below into the service.ini file.

Services=
 Service=
  Name=HttpService80
  ClassName=com.orbitgis.toolx.network.interfaces.http.server.HTTPService
  Parameters=
   Parameter=secure:false
   Parameter=host:all
   Parameter=port:80
   Parameter=http.get.enable:false
   Parameter=http.get.wwwroot:<SYSTEMPATH>/wwwroot
   Parameter=run.service.enable:false
   Parameter=redirect.to.secure:true

Configuration to configure HSTS for the Publisher service.

• https://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security
• https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Strict-Transport-Security

• File : <Install Dir>/program/config/server.ini
• Parameters:
  • http.hsts.enabled: Enable HSTS header
  • http.hsts.maxage: Value for the “max-age” value (defaults to 31536000)
  • http.hsts.includesubdomains: Value for the “includesubdomains” value (defaults to true)
  • http.hsts.preload: Value for the “preload” value (defaults to true)

The default number of concurrent Threads is 32 and a backlog of 64 Tasks.
Related to the available Cores the number of concurrent threads and backlog tasks can be increased.

• <Install Dir>/program/config/server.ini

portserver.HTTP.workthread.count 32 
portserver.HTTP.maximum.pending.requests 64

WebClient - Server communication

The Orbit Publisher includes an HTTP or HTTPS Web Server. One or the other, not both together. Incoming HTTP requests can be redirected to HTTPS services, see below Redirecting from HTTP to HTTPS

By default, an HTTP Web Service is configured. Below desribes the documentation on how to configure an HTTPS Web Service.

The Http(s) Web Service is used for Publisher WebClient (“Publication”) - Server and EOS WebClient (“EOS Console”) - Server communication.

When using https, a certificate file is mandatory. Orbit supports PKCS 12 (.p12), Java KeyStore (.jks) and more (see below).
The password-protected KeyStore file must contain your Private Key and full Certificate Chain from Root to Public Domain Certificate.

Certificate signing and creation is an independent process from the Publisher installation. This must be completed prior to configuring the Orbit Web Server from HTTP to HTTPS. This can be done manually such as Manual CSR Generation or with online tools such as Generate CSR. As CSR generation is different based on each hosted web server, it is not possible to document every method.

For more information on used concepts, see: Wikipedia Authorization Certificate, Wikipedia Public Key, Wikipedia Java Keystore, Wikipedia PKCS 12.

Copy the KeyStore file keystore.xxx to <Install Dir>/../Orbit 3DM Publisher Service Data/http/.
Supported KeyStore files : .jks, .jceks, .p12, .pks, .pfx

Add a keystore.pwd single line text file next to the KeyStore file.
The password can be saved as plain text or scrambled.
To get a scrambled keystore.pwd, create a Service Request to be contacted by a Support Engineer.

Configure the HTTP service to operate in HTTPS mode and port 443 :

• <Install Dir>/../Orbit 3DM Publisher Service Data/http/configuration.ini

secure			true
port			443

Configure the Console to operate in HTTPS mode and port 443 :

• <Install Dir>/Console

URL=https://<Publisher Server URL>/console/

Launch the Console.

File : <Install Dir>/program/config/server.ini

ssl.setup.protocol	TLSv1.3

The following values can be used to set a different TLS policy:

• TLS (any version)
• TLSv1 (or higher)
• TLSv1.1 (or higher)
• TLSv1.2 (or higher)
• TLSv1.3 (or higher)

The activity and tasks completed by the EOS service are logged into the following directory :

• <Install Dir>/../Orbit 3DM Publisher Service Data/log/eos/

These log files contain the most recent activity of the EOS service.
For reasons of disk space, only 10 files of 8MB each are stored. The most recent log file has no index suffix.

• <Install Dir>/program/config/server.ini

system.logfile					<SYSTEMPATH>/log/eos/server.log
system.logfile.pagecount			8 
system.logfile.pagesize				16 
system.logall					true

The activity on Dox and HTTP ports can be logged (default “false”) into the following directory :

• <Install Dir>/../Orbit 3DM Publisher Service Data/log/portserver/

• <Install Dir>/program/config/server.ini

portserver.logging.enabled			false
portserver.logging.interval			10
portserver.logging.location			<SYSTEMPATH>/log/portserver/<TIMESTAMP>.log

By default the EOS service uses TCP port 1100 (DOX), the Orbit Web Service requires port 1111 (HTTP)

Communication between Client and Server must be available at all times. A client, server, or network blocking firewall on these ports will result in run time errors.
The default server and port configuration can be changed if required. However, we do advise to use a reverse proxy instead.

Server-side Service configuration files :

• <Install Dir>/program/services/dox/service.ini
• <Install Dir>/program/services/http/service.ini

Desktop Client side configuration file :

• ../client/program/login.ini

On Windows Orbit uses the Procrun Service to start and run the EOS Service.
The Procrun Service creates by default 2 log files :

• C:/Windows/System32/LogFiles/Apache/name-stderr.date > e.g. “orbit-stderr.2015-04-14” : Log of service install
• C:/Windows/System32/LogFiles/Apache/nname-stdout.data > e.g. “orbit-stdout.2015-04-14” : Log of Procrun Service used by Orbit

The sum of all these files can become very big and may result in the C:/ partition running out of space. Disable this service logging to avoid a relatively small C partition to run out of space.
To disable Procrun logging following server-side configuration file must be updated.

Procrun configurations are set at Service Install. Changing these configurations requires the Orbit Service to be stopped & removed, installed & restarted.

• Windows : <Install Dir>/program/bin64/ServiceInstall.bat

Logging enabled :

--StdOutput=auto
--StdError=auto

Logging disabled :

--StdOutput=
--StdError=

EOS is a running operating system service and is preferably installed and started using an OS administrator account. The used account must have full permission to read and write into the entire Orbit server installation directory. Read access is required for all resources used by EOS.

A proper EOS service start, stop and remove are possible as OS administrator using the Orbit shortcuts within the Orbit installation directory :

• <Install Dir>/program/bin/

Stop & Start

When updating the Orbit Server software or applying hardware maintenance it will be required to stop and restart the Orbit Service. The service needs to be installed before starting and stopped before removing.
Use of the Orbit Service shortcuts is recommended at all time, verify successful Service Install, Start, Stop and Remove using the OS Services Management Console.

Multiple instances

The name of an operating system service supposed to be unique.
To install multiple Orbit Services on a single server the Orbit Service Name of the second instance will need to be renamed before installing :

• Windows : <Install Dir>/program/bin/ServiceInstall.bat

..
set SERVICE_DISPLAY_NAME=Orbit 3DM Publisher Service 2
set SERVICE_DESCRIPTION=Orbit 3DM Publisher Service 2
...
.. //IS//publisher_3dm_2 ..

The availability of the HTTP Web Service or a specific Publication can be verified by requesting respectively the Web Service cross domain configuration or the publication html web page :

• http://<server>:<port>/publications/<publication>/index.html
• http://<server>:<port>/crossdomain.xml

A TestService is available to request detailed runtime information about all EOS Services. Optionally a TestMask can be applied.

• All available tests
  http://<server>:<port>/?service=TestService&request=RunTestOperation
• Service StartTime
  http://<server>:<port>/?service=TestService&request=RunTestOperation&TestMask=ServiceContainer.System.StartTime
• 3DM Publisher Online Check
  http://<server>:<port>/?service=TestService&request=RunTestOperation&TestMask=ServiceContainer.MappingService3DM.ServicesOnline

The 3DM Publisher server includes the capability to provide OGC compliant WFS (version 1.1.1 and 1.2.0) and WMS (version 1.1.0 and 1.3.0) services for Generic Resources.

More information about the OGC WFS and WMS specifications :

• http://www.opengeospatial.org/standards/wfs
• http://www.opengeospatial.org/standards/wms

Resources are published on a Publication level. On the Share page of a Publication, you can enable or disable a dedicated WMS, WFS endpoint for the publication. Basic support for WFS Transactions (WFST) can be enabled separately.

The WFS service supports the following output formats :

• GML 2.1.2
• GML 3.1.1
• GeoJSON