Installation and configuration

Installation

Important

First need to do setting up the environment. All commands are executed only from superuser.

Mode superuser:

sudo -i

Linux

Attention

There is support for user authentication using smart card. More details here.

  1. Install the package RSclient:

    • from Python package repository:

      pip3 install rs-client

    After installing the Linux version of rs-client, it is possible to install additional functionality:

    • To work with smart cards, do the following:

      pip3 install rs-client[smart]

    This action will install the following packages:

    pykcs11
pyopenssl
pyasn1

    • To work with SSO authorization in conjunction with Webgard, do the following:

      apt install libkrb5-dev libcurl4-openssl-dev libssl-dev
pip3 install rs-client[sso]

    This action will install the following packages:

    pycurl
kerberos
pyyaml

    • To work with Kerberos authorization in conjunction with Keystone, do the following:

      apt install libkrb5-dev libcurl4-openssl-dev libssl-dev
pip3 install rs-client[kerberos]

    This action will install the following packages:

    pycurl
kerberos
pyyaml
keystoneauth1

For Astra Linux 1.7

To install RSclient on Astra Linux do following:

  1. Connect the provided repository with AccentOs packages.

  2. Install the package with the command:

    sudo apt install -y aos-rs-client

Attention

Functionality of getting instances by Kerberos tickets for Astra Linux 1.7 is only available when installing the package via pip.

To correctly install RSclient on Astra Linux 1.7 via pip, do the following:

  1. Connect the repositories presented to you with AccentOs packages for Astra Linux 1.7.

  2. Install packages required for Linux.

  3. Additionally, install the packages necessary for work with the command:

    apt install  python3-pyside2.qt3dcore python3-pyside2.qt3dinput python3-pyside2.qt3dlogic python3-pyside2.qt3drender python3-pyside2.qtconcurrent \
    python3-pyside2.qtcore  python3-pyside2.qtgui python3-pyside2.qthelp python3-pyside2.qtlocation python3-pyside2.qtmultimedia  python3-pyside2.qtmultimediawidgets \
    python3-pyside2.qtnetwork python3-pyside2.qtopengl python3-pyside2.qtpositioning python3-pyside2.qtprintsupport python3-pyside2.qtqml python3-pyside2.qtquick  \
    python3-pyside2.qtquickwidgets  python3-pyside2.qtscript  python3-pyside2.qtscripttools  python3-pyside2.qtsensors  python3-pyside2.qtsql  python3-pyside2.qtsvg  \
    python3-pyside2.qttest  python3-pyside2.qttexttospeech python3-pyside2.qtuitools  python3-pyside2.qtwebchannel python3-pyside2.qtwebenginecore  \
    python3-pyside2.qtwebenginewidgets  python3-pyside2.qtwebsockets  python3-pyside2.qtwidgets  python3-pyside2.qtx11extras  python3-pyside2.qtxml  python3-pyside2.qtxmlpatterns

  4. Create a symlink for the missing library:

    sudo ln -s /usr/lib/x86_64-linux-gnu/libxcb-util.so.0 /usr/lib/x86_64-linux-gnu/libxcb-util.so.1

  5. Install the package using the command:

    pip3 install -y aos-rs-client

Windows

Attention

Only 64-bit Windows is supported.

Installing RSclient using the Installer

  1. Follow the link to the repository with client distributions.

  2. Select the version of RSclient compatible with the operating system:

    ../../_images/trs_files_aos.png

    List of clients

  3. Download and run the installer RSclient.1.30.0x64.Setup.exe.

  4. Select installation language:

    ../../_images/trs_install_language.png

    Language selection window

  5. Check out the software product:

    ../../_images/trs_copyright.png

    Module information window

  6. Choose directory for installation:

    ../../_images/trs_directory.png

    Window for selecting directory for installing application

  7. Select folder from the start menu:

    ../../_images/trs_start_directory.png

    Window for selecting a directory for the application shortcut

  8. Confirm installation parameters:

    ../../_images/trs_start_install.png

    Installation start window

    Program launch flag is set by default in the completion window after successful installation:

    ../../_images/trs_finish_install.png

    Installation completion window

    Set the required value and complete the installation with the «Finish» button.

Launching RSclient from the AppImage image

If you need to launch RScleint on unsupported Unix systems, it is possible to work through AppImage; to do this, download the required version of the client from the link.

Give the necessary rights to launch:

chmod +x rsclient-*.AppImage

Start RSclient:

./rsclient-*.AppImage

Attention

For some systems, AppImage can only be launched as root.

Configuration file

When RSclient is launched for the first time in the user’s home directory, configuration file client.conf is created in .rsclient directory.

Some of parameters presented in the configuration file can also be set in the window «RSclient settings». Configuration file is presented in ini format and consists of the following sections and parameters:

Parameter Description Default value Required Ability to set a parameter in the graphical interface
cloud Server primary address. It is need to enter either the server’s IP address or hostname. For example, localhost or 10.10.10.10. This parameter is required. In the case of using the HTTPS protocol, the server address must be specified in the format https://<host name>:<HTTPS port>, for example, https://accentos.ru:8889. If using HTTPS, remember to use the ca_bundle_path option.   Yes Yes
ignore_domain Parameter that ignores the domain_name parameter when generating an rdp file to connect to the guest operating system.   No No
secondary_cloud Secondary server address. It is used to connect if there is no response from primary address. It is need to enter either the server’s IP address or the hostname. For example, ‘localhost’ or ‘10.10.10.10’.   No Yes
domain_name Domain name. default No, if there is no parameter value in the configuration file, default value is used. Yes
log_level

Logging level. Available values:

  • DEBUG;
  • INFO;
  • WARNING;
  • ERROR;
  • CRITICAL.

Values are case insensitive. Detailed description of the parameters is available in the section log levels.

 INFO No, if there is no parameter value in the configuration file, the default value is used. Yes
connect

Remote access client launch command, you can use the following substitutions:

  • {ip} is IP address;
  • {user} is username;
  • {password} is password;
  • {domain} is domain name;
  • {spice_host} is domain name or SPICE console IP address;
  • {spice_port} is SPICE console port;
  • {cups} is parameter passing the value `--use-cups when using the parameter use_cups;
  • {rdp_config} is remote desktop log file, it is generated automatically on Windows platform.
   Yes No
log_file_location Path to the directory in which it is need to create log file. Log file is created in client’s root folder.   No No
store_session

Parameter responsible for saving connection settings, «Remember» flag in the graphical interface. Available values:

  • True is saving parameters of each session;
  • False is deleting parameters of each session.

Values are case insensitive.

 True No, if there is no parameter value in the configuration file, the default value is used. No
use_cups

Parameter responsible for working with CUPS at the guest operating system level. Available values:

  • True - connection to the guest instance is made using CUPS arguments;
  • False - CUPS arguments not being passed to guest instance.

Values are case insensitive.

 False No, if there is no parameter value in the configuration file, default value is used. Yes
language Language of graphical client interface. If this parameter is not specified, then the localization of the operating system on which the client is running is used.   No Yes
project

Changing the display setting of «Project» field in the main RSclient window:

  • True - «Project» field is displayed;
  • False - «Project» field is not displayed, connection is performed without specifying the project.

Values are case insensitive.

 True No, if there is no parameter value in the configuration file, the default value is used. No
show_settings

Changing display of the «Settings» button:

  • True - «Settings» button is displayed;
  • False - «Settings» button is hidden.

Values are case insensitive.

 True No, if there is no parameter value in the configuration file, the default value is used. No
store_password

Parameter responsible for saving password in settings. It does not depend on value of store_session parameter. Available values:

  • True - saving password for each session;
  • False - deleting password for each session.

Values are case insensitive.

 False No, if there is no parameter value in the configuration file, the default value is used. No
PYKCS11LIB Path to libisbc_pkcs11_main.so file, required to work with smart cards. If there is no value, the file is searched for in .rsclient folder of user’s home directory and in the current directory.   No No
SMARTCARD_OID The EKU extension of the required certificate must contain the specified OID. If the parameter is absent, the filtering of certificates by OID is not performed.   No No
ikecfg Parameter specifies the client’s IP address. It allows to transfer to the server an IP address that differs from the current if necessary. it used to create security group rules for the TRS instance transferred to the client.   No No
additional_clouds Additional RSserver addresses. It is used to connect if there is no response from the primary and secondary addresses. It is to enter either the IP address of server or the hostname separated by commas. For example, localhost, 10.10.10.10, myhost.aos.loc.   No No
retries

Number of retries to connect to servers. For example:

  • -1 - Attempts will run endlessly;
  • 1 - Reconnection attempt will be done once;
  • 2 - Two repeated connection cycles will be performed in addition to the main attempt;
  • 3 - Three repeated connection cycles will be performed in addition to the main attempt.
 2 No, if there is no parameter value in the configuration file, the default value is used. No
timeout Waiting time before next connection attempt (in seconds). 15 No, if there is no parameter value in the configuration file, the default value is used. No
contact_support_message_ru Customizable message for contacting the administrator in Russian. Only the first 250 characters are displayed. Обратитесь к системному администратору. No, if there is no parameter value in the configuration file, the default value is used No
contact_support_message_en Customizable message for contacting the administrator in English. Only the first 250 characters are displayed. Please contact system administrator. No, if there is no parameter value in the configuration file, the default value is used No
get_vm_timeout Waiting time before the next attempt to get the task status to get TRS instance (get-vm) (in seconds). The value must be an integer greater than or equal to 0. 5 No, if there is no parameter value in the configuration file, the default value is used. No
request_timeout Maximum request timeout in seconds. When timeout is over, current connection is canceled. 30 No, if there is no parameter value in the configuration file, the default value is used. No
web_guard

Enabling WebGard support. Available values:

  • True - WebGard support is enabled;
  • False - WebGard support is disabled.
 False No, if there is no parameter value in the configuration file, the default value is used. No
use_cert

Enabling Client certificate authentication. Available values:

  • True - certificate authentication is enabled;
  • False - certificate authentication is disabled.
 False No, if there is no parameter value in the configuration file, the default value is used. No
cert Path to user certificate file.   No No
key Path to user private key file.   No No
identity_url Keystone service address, used for client certificate authentication. Use a comma as a separator to specify multiple addresses.   No No
rds Parameter that allows to override the IP address obtained from the Broker API service.   No Yes
kerb_cloud_url Parameter that specifies the address for authorization via Kerberos   No No
minimize_to_tray Parameter responsible for minimizing the window to the system tray after connecting to the instance. False No, if there is no parameter value in the configuration file, the default value is used. No
single_launch Parameter responsible for limiting the number of simultaneously running application processes to one instance. False No, if there is no parameter value in the configuration file, the default value is used. No
custom_credentials Parameter which allowes using authorization data for connection to instance different from those that are used for authorization in OpenStack. False No Yes
use_spice Parameter, when specified in RSserver, in addition to the IP address of instance, the address of the SPICE console is requested. False No No
ca_bundle_path Path to certificates chain file.   No, if there is no parameter value in the configuration file, the value from environment variable REQUESTS_CA_BUNDLE is used. No
rds_enabled Parameter responsible for hiding/enabling the display of the RDS field in the GUI. True No No
use_sso

Using SSO single sign-on technology. Available values:

  • True - SSO technology is active;
  • False - SSO technology is not active.
 False No, if there is no parameter value in the configuration file, the default value is used. Yes
eye_pass_icon Parameter responsible for the ability to hide/show the password in the GUI. True No, if there is no parameter value in the configuration file, the default value is used. No
host_addr Parameter responsible for obtaining an IP-address from the network interface of the system. False No, if there is no parameter value in the configuration file, the default value is used. No
vpn_after_connect

A parameter responsible for the order of connecting to the VPN network. Available values:

  • True - connect to the VPN after authorization;
  • False - connect to the VPN before authorization.
 False No, if the parameter is not specified in the configuration file, the default value is applied. No
vpn_cert_path The path to the VPN configuration file.   No, if the VPN configuration file is not present, the network connection will not be established. No
path_to_msi The path to the VPN client installation file. If the path to an MSI file is specified, and the VPN configuration path is also provided, the installation of the VPN client will be offered upon the start of rs-client.   No No
user_unassign

A parameter responsible for the behavior of the TRS instance when closing RSclient. Available values:

  • `` `` - do not take additional actions;
  • unassign - unbind the user from the assigned TRS instance;
  • delete - remove a TRS assigned instance.
 `` `` No, if there is no parameter value in the configuration file, the default value is used. No
disconnect A command with similar functionality to the connect parameter, which will be executed when RSclient is closed.   No No

Important

If RSclient is used with kerberos and webgard configured via https, then it is necessary:

  1. Specify the webgard address with the protocol type and port. Example: https://wg.loc:9365.
  2. Specify the path to the certificate or certificate chain in the ca_bandle_path parameter.

Configuration files examples

For Windows:

[DEFAULT]
cloud = main.aos.ru
ignore_domain = False
secondary_cloud = 10.10.10.13
domain_name = default
log_level = DEBUG
connect = mstsc {rdp_config}
log_file_location = %USERPROFILE%\.rsclient\
store_session = False
language = ru
project = True
show_settings = True
pykcs11lib =
ikecfg =
additional_clouds = slave.aos.ru, 10.10.10.14
retries = 2
timeout = 15
contact_support_message_ru = Обратитесь к системному администратору.
contact_support_message_en = Please contact system administrator.
сa_bundle_path = /home/user/rootCa.crt
vpn_after_connect = False
vpn_cert_path =

For Linux (with using NX client):

[DEFAULT]
cloud = main.aos.ru
ignore_domain = False
secondary_cloud = 10.10.10.13
domain_name = default
log_level = INFO
connect = /home/user/trs.sh {user} {password} {ip} 2> /dev/null
log_file_location = $HOME/.rsclient/
store_session = False
language = ru
project = True
show_settings = True
pykcs11lib = /usr/lib64/libisbc_pkcs11_main.so
SMARTCARD_OID = 1.3.6.1.4.1.311.20.2.2
ikecfg =
additional_clouds = slave.aos.ru, 10.10.10.14
retries = -1
timeout = 15
contact_support_message_ru = Обратитесь к системному администратору.
contact_support_message_en = Please contact system administrator.
сa_bundle_path = /home/user/rootCa.crt
vpn_after_connect = False
vpn_cert_path =

When RSclient is launched for the first time in the user’s home directory, configuration file rdp.conf.sample is created in .rsclient directory. This file contains basic settings for RDP connection for Windows OS, which can be edited.

Configuring to work with smart cards

Note

Work with smart card is supported only on Linux operating systems.

It is need to do the following steps in order for the module to function with smart cards:

  1. For low-level work with maps, install the packages opensc and pcsc-lite with its utilities:

    # Debian:
apt-get install opensc
apt-get install pcsc-lite pcsc-tools

    Note

    Additionally for the operating system CentOS:

    1. Download and install from repository the latest version of EPEL:

      rpm -Uvh epel-release*rpm

    2. Install package pcsc-tools:

      yum install pcsc-tools

  2. Smart cards work via API PKCS11 and PC/SC. Install the required dependencies initially:

    # Debian:
apt-get install libpcsclite-dev
apt-get install python-module-OpenSSL

  3. Install package pykcs11 for work with smart card via API PKCS11:

    pip3 install pykcs11

  4. Install python-module-pyscard for work with smart card via API PC/SC:

    # Debian:
apt-get install python-module-pyscard

  5. Download the library archive ESMART Token 4.2 (PKCS#11) for Linux. It can be found here.

  6. Then find file libisbc_pkcs11_main.so in the archive and specify the path to the file in the parameter PYKCS11LIB of config file or set as environment variable:

    export PYKCS11LIB="path to libisbc_pkcs11_main.so"

  7. Run the following commands to be able to work with smart card without privileges superuser:

    sed -i "s/no/yes/" /usr/share/polkit-1/actions/org.debian.pcsc-lite.policy
systemctl restart pcscd.socket

  8. Install the following packages to display text correctly when switching the graphical environment X11:

    yum install xorg-x11-fonts*
yum install dejavu-lgc-sans-fonts