Installing orcharhino Proxy on Windows

This guide describes the installation of an orcharhino Proxy on Windows to go along with your orcharhino Server. If you want to use orcharhino to manage hosts in additional networks, you need an orcharhino Proxy installed in each network you want to manage. This allows you to orchestrate the process of managing hosts in different networks, that is networks spanning across different data centres and regions. For more information, see URLs for orcharhino Proxy on Windows in the ATIX Service Portal.

Prerequisites

  • Your host runs Microsoft Windows Server 2016, 2019, or 2022.

  • Your host has access to the internet to install Ruby gems.

  • If you want to manage DHCP and/or DNS, ensure that you install the dnscmd.exe tool.

Procedure

  1. Install dnscmd.exe:

    • Open the server manager and go to Manage > Add Roles and Features.

    • Select Role-based or Feature-based installation > DNS Server and install the DNS server tools.

  2. Install Ruby:

    • Go to rubyinstaller.org/downloads/archives and download Ruby+Devkit for Ruby 2.7.

    • Start the installation. During the Ruby installation process, select option three MSYS2 and MINGW development toolchain. Press Enter to confirm and ignore the warnings.

  3. Install orcharhino Proxy on Windows:

    • After you have installed Ruby, you can install your orcharhino Proxy on Windows. Ensure that your orcharhino Proxy on Windows version matches your orcharhino Proxy on Windows version delivered with orcharhino. In the orcharhino management UI, navigate to Administer > About to view the currently running version.

    • Download the correct orcharhino Proxy on Windows version from ATIX AG. For more information, see URLs for orcharhino Proxy on Windows in the ATIX Service Portal.

    • Extract the zip archive to C:\orcharhino-proxy\.

    • Open a command prompt with administrator rights.

    • Go to C:\orcharhino-proxy\ to ensure all commands are run within the orcharhino-proxy directory.

    • Run C:\Ruby27-x64\bin\gem install --no-document bundler.

    • Run C:\Ruby27-x64\bin\bundle config set without 'development test krb5 puppet_proxy_legacy bmc libvirt'

    • Run C:\Ruby27-x64\bin\bundle install

  4. Generate certificates to secure the communication between orcharhino Server and orcharhino Proxy on Windows:

    • Using the default self-signed certificates:

      • Connect to your orcharhino Server using SSH.

      • Run foreman-proxy-certs-generate --foreman-proxy-fqdn "My_orcharhino_Proxy_On_Windows_FQDN" --certs-tar "/root/My_orcharhino_Proxy_on_Windows_FQDN-certs.tar". You can find the required certificates in /root/ssl-build on your orcharhino Server.

      • Create the target directory on your orcharhino Proxy on Windows: C:\orcharhino-proxy\certs\.

      • Copy the following three certificates to C:\orcharhino-proxy\certs\ on your orcharhino Proxy on Windows:

        • katello-server-ca.crt

        • My_orcharhino_Proxy_On_Windows_FQDN-foreman-proxy.crt

        • My_orcharhino_Proxy_On_Windows_FQDN-foreman-proxy.key

    • Using custom certificates:

      • Locate the required certificates in /root/ssl-build on your orcharhino Server.

      • Create the target directory on your orcharhino Proxy on Windows: C:\orcharhino-proxy\certs\.

      • Copy the following three certificates to C:\orcharhino-proxy\certs\ on your orcharhino Proxy on Windows:

        • katello-default-ca.crt

        • katello-server-ca.crt

        • the custom certificate and key which are provided by your custom CA.

  5. Configure your orcharhino Proxy on Windows:

    • Go to C:\orcharhino-proxy\config\.

    • Rename settings.yml.example to settings.yml.

    • Enter the following content to settings.yml:

      • If you use self-signed certificates:

        :ssl_certificate: C:\orcharhino-proxy\certs_My_orcharhino_Proxy_on_Windows_FQDN_-foreman-proxy.crt
:ssl_ca_file: C:\orcharhino-proxy\certs\katello-default-ca.crt
:ssl_private_key: C:\orcharhino-proxy\certs_My_orcharhino_Proxy_on_Windows_FQDN_-foreman-proxy.key

:bind_host: ['0.0.0.0']
:trusted_hosts:
  - orcharhino_Server_FQDN
  - orcharhino_Proxy_on_windows_FQDN
:foreman_url: orcharhino_Server_FQDN
:https_port: 8443
# only set the "http_port" if you cannot use HTTPS
:http_port: 8000
:log_file: C:\orcharhino-proxy\orcharhino-proxy.log

      • If you use custom certificates:

        :ssl_certificate: C:\orcharhino-proxy\certs_My_orcharhino_Proxy_on_Windows_FQDN_-custom.crt
:ssl_ca_file: C:\orcharhino-proxy\certs\katello-default-ca.crt
:ssl_private_key: C:\orcharhino-proxy\certs_My_orcharhino_Proxy_on_Windows_FQDN_-custom.key

:foreman_ssl_ca: C:\orcharhino-proxy\certs\katello-server-ca.crt
:foreman_ssl_cert: C:\orcharhino-proxy\certs_My_orcharhino_Proxy_on_Windows_FQDN_-custom.crt
:foreman_ssl_key: C:\orcharhino-proxy\certs_My_orcharhino_Proxy_on_Windows_FQDN_-custom.key

:bind_host: ['0.0.0.0']
:trusted_hosts:
  - orcharhino_Server_FQDN
  - orcharhino_Proxy_on_windows_FQDN
:foreman_url: orcharhino_Server_FQDN
:http_port: 8000  # optional
:https_port: 8443
:log_file: C:\orcharhino-proxy\orcharhino-proxy.log

  6. Configure DNS:

    • Go to C:\orcharhino-proxy\config\.

    • Rename dns.yml.example to dns.yml.

    • Enter the following content to dns.yml:

      :enabled: true
:use_provider: dns_dnscmd

    • Rename dns_dnscmd.yml.example to dns_dnscmd.yml.

    • Enter the following content to dns_dnscmd.yml:

      :dns_server: FQDN_of_my_DNS_Server

  7. Configure DHCP:

    • Go to C:\orcharhino-proxy\config\.

    • Rename dhcp.yml.example to dhcp.yml.

    • Enter the following content to dhcp.yml:

      :enabled: true
:use_provider: dhcp_native_ms
:server: FQDN_of_Your_DHCP_Server
:subnets: [192.168.1.0/255.255.255.0]

      Note that the subnets parameter is optional for filtering. If you do not specify it, orcharhino Proxy on Windows checks all subnets in DHCP. If you want to manage several subnets, use a comma-separated list.

    • Rename dhcp_native_ms.yml.example to dhcp_native_ms.yml.

    • Enter the following content to dhcp_native_ms.yml:

      :disable_ddns: true/false

  8. Open a command prompt with administrator rights.

  9. Configure the firewall to allow orcharhino Server to access your orcharhino Proxy on Windows:

    # netsh advfirewall firewall add rule name=\"orcharhino-proxy-HTTPS\" dir=in localport=8443 protocol=TCP action=allow

# only if you cannot use HTTPS
# netsh advfirewall firewall add rule name=\"orcharhino-proxy-HTTP\" dir=in localport=8000 protocol=TCP action=allow

  10. Start your orcharhino Proxy on Windows manually:

    • Open a command prompt with administrator rights and execute following commands:

      • cd C:\orcharhino-proxy\bin\

      • bundle exec smart-proxy

  11. Add your orcharhino Proxy on Windows to orcharhino:

    • In the orcharhino management UI, navigate to Infrastructure > Smart Proxies.

    • Click Create orcharhino Proxy.

    • Enter the name and URL of your orcharhino Proxy on Windows.

      If you use HTTPS, enter https://orcharhino-proxy-on-windows.network3.example.com:8443. If you use HTTP, enter https://orcharhino-proxy-on-windows.network3.example.com:8000.

  12. Assign orcharhino Proxy service: You need to assign a service user to your orcharhino Proxy on Windows that is a member of the DHCP administrator group and the permission to log-in as a service user. For more information, see Enable Service Logon. To create a orcharhino Proxy service, open a command prompt with administrator rights and execute following commands:

    # cd C:\orcharhino-proxy\
# ruby extra\register_service.rb

  13. Add additional orcharhino Proxy on Windows instances on same host: In a orcharhino Proxy on Windows instance, you can only assign one system user to manage DNS and DHCP entries. You can copy the orcharhino-proxy directory to another path with a different name to run multiple instances of your orcharhino Proxy on Windows on the same host. Doing so requires using different ports and service names. This allows you to use different users for DHCP/DNS or to connect to other DNS/DHCP servers if required, without having to setup multiple hosts running Microsoft Windows. If DHCP and DNS cannot be managed with the same user, you can create a second instance assigning a second user and the corresponding role on the same orcharhino Proxy on Windows.

    • Copy the existing orcharhino-proxy directory to a second directory, for example orcharhino-proxy-dhcp.

    • Edit settings.yml and assign a different port other than 8443, for example 8444.

    • Ensure that your orcharhino Server can access port 8444:

      • Configure the firewall on your orcharhino Proxy on Windows:

        # netsh advfirewall firewall add rule name=\"orcharhino-proxy-HTTPS\" dir=in localport=8444 protocol=TCP action=allow

      • Ensure SELinux on your orcharhino Server allows to connect to port 8444:

        # semanage port -a -t http_port_t -p tcp 8444

    • The remaining steps are identical to the first instance.

Upgrading orcharhino Proxy on Windows

Procedure

  1. Stop your orcharhino Proxy service.

  2. Rename your orcharhino-proxy directory, for example to orcharhino-proxy-old.

  3. Download the new orcharhino Proxy on Windows version and install it.

  4. Copy the configuration and certificates from the orcharhino-proxy-old directory to the new orcharhino-proxy directory.

  5. Start your orcharhino Proxy service.