fixes #12006 - update Windows smart proxy instructions

Closes GH-441
theforeman · Nov 30, 2015 · c8d70d8 · c8d70d8
1 parent 97a8bcf
commit c8d70d8
Show file tree

Hide file tree

Showing 2 changed files with 68 additions and 83 deletions.
diff --git a/_includes/manuals/1.10/4.3.1_smartproxy_installation.md b/_includes/manuals/1.10/4.3.1_smartproxy_installation.md
@@ -19,6 +19,57 @@ You can get the latest stable code from [GitHub](https://github.com/theforeman/s
 git clone git://github.com/theforeman/smart-proxy.git
 </pre>
 
+#### Windows
+The Microsoft smart-proxy installation procedure is very basic compared to the RPM or APT based solution. You need to run smart-proxy from the source as well as install Ruby and Ruby DevKit. Smart proxy supports __ruby >= 1.9.3__ on Windows.
+
+1. Run [Ruby Installer](http://rubyinstaller.org/downloads/) and add the matching DevKit to compile native extensions. Make sure to add Ruby to `%PATH%`, you can select this option in the installer
+1. Download / clone the [smart proxy repository](https://github.com/theforeman/smart-proxy) to a convenient location (see above, _Source Code_). Make sure to download / checkout the maching branch to your foreman installation
+1. Open a command prompt (`cmd.exe`) and run the following commands in order:
+    1. `ruby <devKitRoot>\dk.rb init`
+    1. `ruby <devKitRoot>\dk.rb install`
+    1. `gem install --no-ri --no-rdoc bundler`
+    1. `cd <smart-proxy location>`
+    1. `bundle install --without development test krb5 puppet puppetca bmc`
+
+##### General configuration
+1. Create the SSL certificate and key
+    1. Login to your puppetmaster
+    1. On the command line, type the following command. Take care not to use an alias nor upper case characters.
+
+           puppet cert generate smart-proxy-FQDN
+
+    1. Copy the private key, the public certificate and the ca.pem from /var/lib/puppet/ssl over to the location accessable by smart proxy, Eg `<smart-proxy location>\ssl\`
+1. Copy *settings.yml.example* inside *config* to *settings.yml*
+1. At very least, modify the settings for `:bind_host:` and `:log_file:` and SSL, for example:
+
+```
+:bind_host: '0.0.0.0'
+:log_file: 'C:\smart-proxy.log'
+
+:trusted_hosts: [ foreman.example.com ]
+
+:ssl_certificate: <smart-proxy location>\ssl\host.example.com.pem
+:ssl_private_key: <smart-proxy location>\ssl\host.example.com.pem
+:ssl_ca_file:     <smart-proxy location>\ssl\ca.pem
+
+```
+
+##### Test and configure smart proxy features
+1. Test your configuration by setting `:log_level: DEBUG` and `:log_file: STDOUT` in *config/settings.yml*
+1. Open an administrative command prompt and run `ruby <smart-proxy location>\bin\smart-proxy`
+1. [Configure smart-proxy features like DNS and DHCP](manuals/{{page.version}}/index.html#4.3.2SmartProxySettings)
+1. Once everything runs well install a Windows service using `ruby extra\register-service.rb` to register the service `Foreman Smart Proxy`. Alternatively, use a third party tool like [NSSM](https://nssm.cc/) to create the service.
+
+__Caveats:__ There is an issue with DevKit not finding any ruby version installed. Check that the DevKit and Ruby Installer are both x32 or x64, otherwise [add the missing versions manually by editing `config.yml`](https://github.com/oneclick/rubyinstaller/wiki/Development-Kit#4-run-installation-scripts).
+
+__Puppet hint:__ If you have Puppet installed on the same host running smart-proxy, you can use Puppet's Ruby. You only need DevKit. In this case, just add directory containing `ruby.exe` to your path variable and add it to DevKit settings if necessary by editing DevKit's `config.yml`. Also, you might want to use Puppet's host certificates right away for smart proxy SSL connections. Usually, they can be found in `C:\ProgramData\PuppetLabs\puppet\etc\ssl`. For example:
+
+```
+:ssl_certificate: C:\ProgramData\PuppetLabs\puppet\etc\ssl\certs\host.example.com.pem
+:ssl_private_key: C:\ProgramData\PuppetLabs\puppet\etc\ssl\private_keys\host.example.com.pem
+:ssl_ca_file:     C:\ProgramData\PuppetLabs\puppet\etc\ssl\certs\ca.pem
+```
+
 #### Configuration file
 
 Usually can be found at /etc/foreman-proxy/settings.yml or in the config/settings.yml subdirectory.

diff --git a/_includes/manuals/1.10/4.3.4.3_ms_dhcp.md b/_includes/manuals/1.10/4.3.4.3_ms_dhcp.md
@@ -1,96 +1,30 @@
-
-The Microsoft smart-proxy installation procedure is very basic compared to the RPM or APT based solution.
-
 It is required that this procedure is executed as an administrator.
 
-It is not required that the smart-proxy be on the same host as the MS dhcp server.  The smart-proxy just needs to be on a windows host that has netsh commands available.
-
-1. Go to the smart-proxy repository at https://github.com/theforeman/smart-proxy/releases
-2. Just under the tag matching your Foreman version, click the ZIP link in order to download the Smart Proxy source code
-3. Extract the archive to a directory that does not have any spaces in its name
-4. Go to the rubyinstaller web page at http://rubyinstaller.org/downloads/
-5. Download and install the "ruby 1.9.3-p551": (Allow the ruby associations to be installed.)
-6. Download and install the Development Kit For Ruby 1.9.3: (DevKit-tdm-32-4.5.2-20111229-1559-sfx.exe)
-7. Open a CMD window and, install the bundler_ext gem using *gem install --platform x86-mingw32 bundler*
-8. CD to the root of the smart-proxy directory (the one you created in step 3)
-9. Copy the file Gemfile to GemFile.in : *copy Gemfile GemFile.in*
-10. Install all the dependencies using bundler : *bundle install --without krb5 puppet puppetca*
-
-11. Edit config/settings.yml so that it looks a bit like this
-
-    _Sample config/settings.yml file_
+It is not required that the smart-proxy be on the same host as the MS dhcp server. The smart-proxy just needs to be on a windows host that has netsh commands available. If this is the case, make sure the smart proxy service runs as a user with sufficient privileges.
 
-        ---
-        # Web site conf
-        #:bind_host: 10.10.10.1
-        :http_port: 8080
+__Note:__ Refer to the [installation guide](manuals/{{page.version}}/index.html#4.3.1SmartProxyInstallation) for general setup.
 
-        # SSL settings
-        :https_port: 8443
-        :ssl_certificate: c:\documents\smart-proxy\config\signed.pem
-        :ssl_private_key: c:\documents\smart-proxy\config\private.pem
-        :ssl_ca_file:     c:\documents\smart-proxy\config\ca.pem
-
-        :trusted_hosts: [ foreman.someware.com]
-
-        :daemon: false
-
-        # Where our proxy log files are stored
-        # filename or STDOUT
-        # Unix setting
-        #:log_file: log/proxy.log
-        # Windows setting
-        :log_file: c:\tmp\proxy.log
-        # valid options are
-        # WARN, DEBUG, ERROR, FATAL, INFO, UNKNOWN
-        #:log_level: DEBUG
-        :log_level: ERROR
-
-12. Edit config/settings.d/dhcp.yml so that it looks a bit like this
+1. Edit config/settings.d/dhcp.yml so that it looks a bit like this. `:dhcp_server:` can be left commented out if smart proxy runs on the same host.
 
     _Sample config/settings.d/dhcp.yml file_
 
-        ---
-        # Can be true, false, or http/https to enable just one of the protocols
-        :enabled: true
-        # Enable DHCP management
-        :dhcp: true
-        # The vendor can be either isc or native_ms
-        :dhcp_vendor: native_ms
-        # The dhcp_server is only used by the native_ms implementation
-        :dhcp_server: 10.10.10.1
-
-13. Create the SSL key
+       ---
+       # Can be true, false, or http/https to enable just one of the protocols
+       :enabled: true
+       # Enable DHCP management
+       :dhcp: true
+       # The vendor can be either isc or native_ms
+       :dhcp_vendor: native_ms
+       # The dhcp_server is only used by the native_ms implementation
+       :dhcp_server: 10.10.10.1
 
-    - Login to your puppetmaster
-
-    - On the command line, type the following command. Take care not to use an alias nor upper case characters.
-
-            puppet ca generate _Smart-proxy FQDN_
-
-    - Copy the private key, the public certificate and the ca.pem from /var/lib/puppet/ssl over to the locations that you specified in the setting file.
-
-14. If needed, you have to create the option 60 on the Windows DHCP (for PXE Boot)
+2. If needed, you have to create the option 60 on the Windows DHCP (for PXE Boot)
 
     - Open an administrator command prompt
     - Create the PXE Option using netsh
 
-            C:\Windows\system32>netsh
-            netsh>dhcp
-            netsh dhcp> server 10.10.45.1
-            netsh dhcp server>add optiondef 60 PXEClient String 0 comment= PXE Support
-
-15. Test the installation by running ruby bin\smart-proxy.rb within an administrator cmd.exe prompt.
-16. Install the program as a service
-
-    - Install the dependencies to create the service :
-
-            gem install --platform x86-mingw32-60 win32-service
-
-    - Use the script in extra to create the service
-
-            ruby extra\register-service.rb
-
-    This may install the service but not run it. If so then try to start the service from the Ordinary Microsoft services snapin utility.
+          C:\Windows\system32>netsh
+          netsh>dhcp
+          netsh dhcp> server 10.10.10.1
+          netsh dhcp server>add optiondef 60 PXEClient String 0 comment= PXE Support
 
-17. You may test connectivity by running the *extra\query.rb* utility from your foreman host. (Note that this file comes from the _extra_ directory in the smart-proxy release.)