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_.
-
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.
-
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.
-
-
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.
-
-
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 theorcharhino-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
-
-
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.
-
-
-
-
Configure your orcharhino Proxy on Windows:
-
Go to
C:\orcharhino-proxy\config\
. -
Rename
settings.yml.example
tosettings.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
-
-
-
Configure DNS:
-
Go to
C:\orcharhino-proxy\config\
. -
Rename
dns.yml.example
todns.yml
. -
Enter the following content to
dns.yml
::enabled: true :use_provider: dns_dnscmd
-
Rename
dns_dnscmd.yml.example
todns_dnscmd.yml
. -
Enter the following content to
dns_dnscmd.yml
::dns_server: FQDN_of_my_DNS_Server
-
-
Configure DHCP:
-
Go to
C:\orcharhino-proxy\config\
. -
Rename
dhcp.yml.example
todhcp.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
todhcp_native_ms.yml
. -
Enter the following content to
dhcp_native_ms.yml
::disable_ddns: true/false
-
-
Open a command prompt with administrator rights.
-
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
-
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
-
-
-
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, enterhttps://orcharhino-proxy-on-windows.network3.example.com:8000
.
-
-
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
-
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 exampleorcharhino-proxy-dhcp
. -
Edit
settings.yml
and assign a different port other than8443
, for example8444
. -
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
-
Stop your orcharhino Proxy service.
-
Rename your
orcharhino-proxy
directory, for example toorcharhino-proxy-old
. -
Download the new orcharhino Proxy on Windows version and install it.
-
Copy the configuration and certificates from the
orcharhino-proxy-old
directory to the neworcharhino-proxy
directory. -
Start your orcharhino Proxy service.