3.6 Environment and user account control
Purpose
The purpose of this document is to give guidance when installing and configuring RayGateway. The document also contains troubleshooting guidelines for common issues.
For information on configuration of RayGateway endpoints in RayStation, refer to the latest available version of the RayStation User Manual.
Contact information
Report errors or send questions to the RaySearch support e-mail: support@raysearchlabs.com
Definitions
|
Term |
Meaning |
|
AD |
Active Directory |
|
DICOM |
Digital Imaging and Communications in Medicine |
|
IDMS |
Data management system from Accuray |
|
Note: |
This document replaces document RSL-D-61-334. |
2.1 Deployment overview
Below is an overview of the systems that communicate with RayGateway.
Figure 1 RayGateway deployment overview.
· RayGateway runs as a stand-alone server and listens for any connections from RayStation applications.
· A single Accuray IDMS endpoint must be configured per RayGateway instance.
There are no specific requirements on the physical deployment of RayGateway. Firewall and subnets must be configured appropriately (not described in this document).
2.2 Version requirements
The installed version of RayGateway should match that of the RayStation installation.
All communications between RayStation and RayGateway require a matching version which means that the first three version numbers must be the same. For example, 12.3.4.0 matches version 12.3.4.9.
As from version 2023B: If there is a version mismatch, any RayStation activity should fail with a message specifying the mismatching versions.
Retrieving the status (query "/status") of the service via a browser (see Connection_status_page) is exempt from version validation.
3.1 Prerequisites
Before installing RayGateway, a user account should be created in IDMS. The MAC and IP addresses of the computer running RayGateway need to be licensed in IDMS. For more information, contact Accuray.
It is not recommended to install RayGateway before ensuring a properly configured IDMS.
3.2 Installing RayGateway
RayGateway is installed from the RayStation installation package.
1. Select Custom setup and select to include RayGateway.
Figure 2 RayStation installer.
2. Click Next. The RayGateway installer opens.
Figure 3 RayGateway installer.
3. Set the installation parameters:
o Enter Hostname to IDMS. This should be a fully qualified domain name when IDMS is using SSL.
o Enter IDMS Port. The IDMS default port is normally 4027.
o Enter IDMS Username.
o Enter IDMS Password.
o Select IDMS Version. Select 2x for IDMS 4.0.1 and 3x for IDMS 5.x.x.
Figure 4 IDMS Version selection.
o Select Require RayGateway authorization to enable basic AD group membership authorization. If selected, also enter the Authorization Group that users of RayStation must belong to.
4. Complete the installation by clicking Next.
|
Note: |
Be aware that RayGateway will not operate unless a correctly signed license file is placed in the installation folder. For more information, see Approved_IDMS_versions. |
3.3 Configuration
RayGateway Service
RayGateway is installed with a default configuration that can be changed after the installation. The configuration file RayGatewayConfig.xml is found in the installation folder.
The following parameters can be used for configuring the RayGateway Service:
· Port: The server port number used for incoming connections. Possible values are 1 – 65535 (TCP port range). Default value is 7809. Before selecting a custom port, ensure that the port is available (e.g., use command 'netstat -p TCP -an').
· Log File: File path to log. Target directory must exist and must be writable.
· Record Mode: Enables or disables record mode. Possible values are true and false. The record mode should be set to false in daily use (otherwise a lot of data will be accumulated over time). true should only be used for troubleshooting.
o When exporting plans to IDMS, the exported DICOM files will be stored in the Record Mode folder (applies to all versions of RayStation).
o When importing a machine from IDMS (to RayPhysics), the retrieved machine files from IDMS will be stored in the Record Mode folder (only applies to RayStation 8B and later).
· Record Mode Folder: Storage location of DICOM files when Record Mode is enabled. Directory must exist and must be writable.
· PlanNameFormat: Can be used to decide what to be set as the plan name in IDMS. A combination of the RT Plan Name (defined by the value %name% in the configuration) and RT Plan Label (defined by the value %label% in the configuration) from the exported DICOM file can be selected for the created plan name in IDMS. It is also possible to select only one of the values to be used for plan name creation in IDMS.
PlanNameFormat is not included in the configuration by default. If the parameter is not defined, the created plan name in IDMS will use the format "<RT Plan Name>_<RT Plan Label>".
Example configuration: %name%_%label%
· UseAuthorization: This is initially set from the RayGateway installer but can be changed afterwards. Set this to either true or false.
· AuthorizationGroup: This is initially set from the RayGateway installer but can be changed afterwards. Only applies if UseAuthorization is set to true. Enter the name of the Active Directory group that the executing user of RayStation belongs to. Using the command 'whoami /groups' will provide a list of groups that the current user belongs to.
Figure 5 RayGateway configuration file.
IDMS endpoints
The IDMS endpoint is configured during the RayGateway installation but can also be viewed or modified after installation. The file idmsConfiguration.xml is located in the installation folder.
Figure 6 IDMS configuration file.
A correctly signed file ApprovedVersions.xml, provided separately, contains the versions of IDMS that are accepted by RayGateway.
Send the request for the file to: support@raysearchlabs.com
The file is placed in the installation folder.
Figure 7 The file ApprovedVersions.xml.
Changing IDMS version
If the Version field in the file idmsConfig.xml is changed, the RayGatewayBootstrapper needs to be run. This will make sure that the correct version of the CDMS libraries, used to communicate with IDMS, is copied to the installation directory. If incorrect DLLs are loaded when starting RayGateway, the service will shut down.
RayGatewayBootstrapper is located in the RayGateway installation directory.
Configuring SSL settings for iDMS 3x
IDMS 3x requires an SSL connection and therefore requires the following:
· The IDMS host parameter must be an FQDN (e.g., not an IP address). The default is idms-data-svr.accuray.product but depends on site configuration.
· The host running RayGateway must have the trusted certificate installed. This is available from the IDMS dashboard.
Go to https://idms-data-svr.accuray.product:4042/dashboard [idms-data-svr.accuray.product] or contact Accuray service.
SSL connection issues might give the following error reasons:
C007: Iccl Peer receiving exception: C069: receiveExpectedToken failed: Unable to read data from the transport connection: Connection in progress forcibly interrupted by the remote host
3.4 Running RayGateway
RayGateway can be run as a command-line application or as a Service.
The Service can be installed from the command-line using the 'install' command.
A complete list of commands and instructions is presented by running the command 'help' (installationDirectory\RaySearch.RayGateway.RayGatewayService.exe help).
Figure 8 Running the 'help' command.
3.5 Connection status page
When all steps above have been performed and RayGateway has been started, the connection status can be seen via a web browser by entering the following address:
<raygateway host>:<raygateway port>/status
If RayGateway is connected correctly, the status should be Connection OK. If not, an error message is displayed.
Figure 9 Running the "/status" query.
3.6 Environment and user account control
Configuring the host environment
· The RayGateway Service requires read access to the following directories:
C:/Windows/System32
C:/Program Files/RaySearch Laboratories/<RayGateway directory>
· The RayGateway Service requires permissions to bind HTTP sockets to port 7809 (done using the netsh utility).
Security recommendations
· Move the installation of RayGateway Service to a virtual server (a new server is recommended), not containing sensitive information or running other services (particularly move from shared app servers such as Citrix servers). Move to a non-domain joined server with the sole purpose of hosting RayGateway (if the server must be domain joined, make sure that it only has limited permissions in the domain).
· Change the RayGateway service account from LOCAL_SYSTEM to a low privileged service account (local user or domain user account, depending on if the server is domain joined or not).
· Check that the RayGateway Service account has limited permissions on the server and on the network.
o Limit file write to c:\temp.
o No database access to databases on the network.
o No read access to network shares, if available.
· Limit the incoming IP access to only include the RayStation machines. Deny other traffic.
· (Optional) Limit outgoing IP access to required services (for example windows update and IDMS). Configure the server to use a proxy for outbound communications.
· Treat the machine as low trust, i.e. restrict access for domain admins or other high privileged AD accounts to login and leave cached credentials on the server.
RayGateway writes and reads several files when communicating with IDMS. These files are transient and will be deleted immediately when not used anymore. In all cases, the files will be placed in the current user's temporary folder (either directly or within a temporary directory).
This root directory for all transient files and directories is the first of the following paths found:
· The path specified by the TMP environment variable.
· The path specified by the TEMP environment variable.
· The path specified by the USERPROFILE environment variable.
· The Windows directory.
The naming of some transient files is taken from the original file name of the source (i.e., IDMS file storage). The known names are based on the file type. The following are some examples:
$"CT{sopInstanceUid}.dcm"
$"RTDOSE{sopInstanceUid}"
$"StructureSet~{planSignatureId}.dcm"
$"FinalDeliveryPlan~Final~{planSignatureId}.dplan"
$"FinalDeliveryPlan~Optimization~{planSignatureId}.dplan"
$"FinalDeliveryPlan~StaticCouch~{planSignatureId}.dplan"
$"TomoPlanDetails~{planSignatureId}.xml"
$"dose_data~{planSignatureId}.xml"
$"BeamShapes~{planSignatureId}.xml"
$"FinalDose~{planSignatureId}.dcm"
$"OptimizedDose~{planSignatureId}.dcm"
$"GeneralPlan~{planSignatureId}.xml"
$"VoiSetWithOrthogonalContours~{planSignatureId}.xml"
"GeneralPlan.xml"
"GeneralPlan1.xml"
"jaw2field.config"
"jaw2field1.config"
"RP.dcm"
"RD.dcm"
"RS.dcm"
$"CT{i++}.dcm"
The format $"str" is a string interpolation where the text inside the curly braces refers to a variable name. As an example, $"Hello {var}" renders "Hello World" in the case of var being "World".
It is not recommended to use any periodic file scanners, such as anti-virus software, as this potentially blocks transient files from being deleted. If any such service must be used, it should be set up to ignore the known transient files, or preferably the current user's temporary folder altogether.
3.7 Troubleshooting
RayGateway does not start properly
If RayGateway does not start properly, or the connection to IDMS cannot be established, there might be a problem with the file ApprovedVersions.xml.
If the file has not been copied to the installation folder or if it is not signed correctly, RayGateway Service will show an error message.
Figure 10 Error if the file ApprovedVersions.xml is not correctly signed.
RayGateway cannot connect to IDMS
If RayGateway is unable to connect to IDMS, the RayGateway Service will not be able to run and will show an error message. (As from RayStation 7, error messages received from IDMS are shown on the status page.)
Figure 11 Example of error message when RayGateway cannot connect to IDMS.
There are several possible reasons for connection issues:
· The host or port of the IDMS system might be incorrect.
· The file ApprovedVersions.xml might not contain the correct IDMS or RayGateway versions.
· The IDMS password or user name provided in the file IDMSConfig.xml might be incorrect.
· The MAC address of the computer running RayGateway might not be properly licensed in IDMS. This needs to be fixed by Accuray.
· IDMS white list is not correct which produces an error message containing "PM Unable to service request - server is in Version state" or "Unknown Location". This needs to be fixed by Accuray.
Command-line inaccessible when RayGateway Service is running
If RayGateway is running as a Service, the command-line interface cannot be used.
Figure 12 Error when trying to run RayGateway Service when it is already running.
Error "The directory is not empty"
When exporting a Tomo Helical or Tomo Direct plan to IDMS, the user in RayStation might experience the following error:
Figure 13 Error when temp directory is not properly cleared.
This error message is shown when RayGateway fails to delete transient data.
RayGateway creates temporary files when sending data to IDMS. This data is written to the temp directory (for more information, see Temporary_file_handling). If these files cannot be deleted immediately by RayGateway, an exception will be thrown that aborts the transaction. This might cause issues with the patient state in IDMS. It will also cause a leak of temporary files that must be deleted manually.
A possible reason to why this happens is that some application is blocking files (such as anti-malware software, or manually by a user).
The temp directory can be configured by setting the environmental variables (for more information, see Temporary_file_handling).