Command Line Deployments of DxOdyssey

Applies to…

  • DxOdyssey 19.0 and newer

Summary

DxOdyssey may be deployed on any server from the command line by using DxCli without the need to use the DxOdyssey UI.

Information

This KB covers how to setup a gateway group and configure tunnels, clients and groups from the command line. For large deployments, it is recommended to use DH2i’s automated deployment scripts. These scripts use the same steps outlined below but only require that the user configure a setup file and execute the script on each gateway server.

If setup is being performed within a Docker container, please see this KB article for initializing DxOdyssey Docker containers. Besides the initial setup of the container and port mappings, deployment is identical between Docker containers and any other server.

  1. Setup the first gateway.
      1. Execute “dxcli set-secret” to set the gateway group passkey. This is required for other gateways to be able to join the gateway group without using DH2i’s NAT match agent.
      2. Activate the server with a license key by executing “dxcli activate-server < license_key >”.
      3. Execute “dxcli set-otpk” to generate a One-Time Pass Key (OTPK) so other gateways may join using DH2i’s NAT match agent.
      4. Copy the key.
      5. If the gateway is a Docker container, execute the runfirst.sh script in the container’s root directory.
  1. Setup additional gateways.
      1. On another gateway, execute “dxcli join-gateway-group”.
      2. Follow the prompts to use DH2i’s NAT match agent and the previously generated OTPK to join the gateway to the gateway group. 

NOTE: If an alternative matchmaking service is being used, enter that web address instead. Pressing enter with no input will use the default matchmaking service.

      1. Activate the server with a license key by executing “dxcli activate-server < license_key >”.
      2. If the gateway is a Docker container, execute the runfirst.sh script in the container’s root directory. 

NOTE: All proceeding steps in this KB are executable on any gateway in the gateway group, and all steps besides tunnel creation are optional. These commands have specific syntax requirements, so it is important to follow the supplied command usage and examples.

  1. Add clients to the gateway group by executing “dxcli update-client”.
    • dxcli update-client < client_name > < client_password >
    • An example: 
dxcli update-client client1 Passw0rd
  1. Create client groups by executing “dxcli update-client-group”.
    • dxcli update-client-goup < group_name >:< client_name >,< client_name >
    • An example: 
dxcli update-client-group group1:client1,client2,client3
  1. Create tunnel groups by executing “dxcli gateway-group-add-tunnel-group”.
    • dxcli gateway-group-add-tunnel-group < virtual_ip > < gateway_node >,< gateway_node > 

NOTE: If you supply the loopback address for the virtual IP, then add an asterisk (*) at the beginning.

    • An example: 
dxcli gateway-group-add-tunnel-group *127.0.0.1 Server1,Server2
  1. Create source filters by executing “dxcli update-addressfilter”.
    • dxcli update-addressfilter < filter_name > < filter_address >:< filter_action > < default_action >
    • An example: 
dxcli update-addressfilter filter1 10.10.1.0:allow deny
dxcli update-addressfilter filter2 10.10.2.0:deny allow
  1. Create tunnels by executing “dxcli add-tunnel”. It is optional to add a source filter and/or gateway group, so those options may be omitted. 

NOTE: Docker containers require that exposed ports are mapped before the container is started. For more information please see the links at the end of this article.

    • dxcli add-tunnel < tunnel_name > < enabled_status > < destination_gateway > < destination_address >:< port > < origin_gateway >/< origin_address >:< port >[/< source_filter_name >] [< tunnel_group_name >]
    • An example: 
dxcli add-tunnel Tunnel1 TRUE Server1 10.1.201.190:3389 Server2/0.0.0.0:25001 TUNNELGROUP1
  1. Add clients and client groups to tunnels by executing “dxcli update-tunnel-clients”.
    • dxcli update-tunnel-clients < tunnel_name > < client_name >:< listener_ip >:< port > < group_name >:< listener_ip >:< port >

NOTE: Clients need to be defined first and groups second. If no clients are being added, then replace the client section with empty double quotes (“”).

    • An example: 
dxcli update-tunnel-clients Tunnel1 client1:127.0.0.1:50001 group1:127.0.0.1:50001
dxcli update-tunnel-clients Tunnel1 "" group1:127.0.0.1:50001

Additional Information