farmerswife

Welcome
Login  Sign up

How to SSL farmerswife using your "own" certificates, "Proxy WIFE Server" mode and more ...

Last updated: 17. October 2017
farmerswife (fw) is shipped “Out of the box” with our own self-singed certificates in place, to ensure that at least the communication between the fw Server and the fw Client Desktop software and the native iOS farmerswife app is “SSLed” – we consider this to be a “closed” environment. The Web Client and Mobile Web Client are not SSLed by default; they live in a very different environment - i.e a web browser. And to use here our own self-signed certificates is in our eyes counter-productive from a end-user’s point of view: self-signed certificates are labeled as “not secure”.
We therefore strongly recommend that you SSL-ify your farmerswife system, by using your “own” SSL certificates.
These instructions are to be used by fully qualified IT-Admins

Three fundamentally different approaches are covered to get the farmerswife system SSLed:

  1. By SSL-ifing the actual farmerswife Server application (chapter “SSL-ify the actual farmerswife Server by using your own cert...”).
  2. By running a fw Server in a special “Proxy WIFE Server” mode on a machine in your DMZ (demilitarized zone), see chapter "Use the “Proxy WIFE Server” mode on a DMZ-hosted machine".
  3. By using a “proxy”, to here apply your own SSL certs (chapter "Use a "Proxy" to apply your SSL certificates) and redirecting all traffic to the fw Server through this proxy.

In order to provide access to the complete functionality of the fw Server application 5 different ports (one is used by two different services) need to be considered when making it “internet facing”. Two of these ports are non-http. And the fw Server application can use a specific port value only once!
To grant access you can open and port-forward these 5 ports to the computer hosting the fw Server application on your internet router / firewall / gateway.
Or, you can set-up 5 different DNS-records and use the standard “web service” ports 80 and 443 and one more, e.g. 8080 or 8443, which are typically not blocked for TCP incoming and outgoing traffic - even within “corporate” network environments.

The following tables tries to provide an overview with examples to describe the 3 different approaches. The naming convention within the examples consider using one pre-existing wildcard certificate following this format: fw-AccessTier.example.org:

Overview of the above 3 approaches by using the farmerswife v6.3 DemoDB, by going into the Setup > General tab:

fw Server Port settings name

fw Server Port value on DemoDB


SSLed by default*

Example URLs / DNS with re-direction 

1) SSLify the fw Server without redirection

2) “Proxy WIFE Server” mode on DMZ

3) “Proxy” port values

Server Port
(non-http)

22000
(TLS over TCP)

Yes
fw-client.example.org
22000
N/A use VPN
80
Filetransfer Port 
(non-http)

24000 ***
(TCP)

-
- **
24000 ***
N/A use VPN
8080 ***
API Port 

25000
(XML over HTTPS)

Yes
fw-ios.example.org
25000
25000 or 443 via own DNS
443 via own DNS
Web Client Port

26000 ****
(HTTP)

-
fw-web.example.org
443 ****
26000 or 443 via own DNS ****
443  via own DNS ****
Mobile Web Client

26000 ****
(HTTP)

-
fw-mobile.example.org
443/mobile ****
26000 or 443 via own DNS ****
443 via own DNS ****
Legacy Http Port

27000
(HTTP)

-
fw-webcal.example.org

27000
27000 or 443 via own DNS
443 via own DNS +*****

* "SSLed by default": The "Server Port" (used by the fw Client Desktop app) and "API Port" (used by the iOS farmerswife app) both use our own self-signed-certificates (these are default fw Server-side built-in "skey.pem" and "server.pem", more info below). We consider this to be closed and thus secure
** A domain name is not needed, since this is used by the fw Client application.
*** Feature development to be able to set the "Proxy Port (Only If Used)" on next v6.4 will make this possible, more info below.
**** Since v6.0 it's possible to control whether the Web Client Port is automatically added to the URL defined in "Url To Server", more info below.
***** When using a "proxy" double re-direction for the "Open WebCal Index" will be needed as well, more info below.

Use the “Server Ports and Access Tiers” documentation for even more information on the fw Server’s ports and their usage.

SSL-ify the actual farmerswife Server by using your "own" certificates

The examples used in this how-to explain the whole process when running the WIFE Server on a Windows machine and using an existing “wild card” SSL certificate from “DigiCert” (used by chance, no kick-back on our side). You do not have to use a wild card certificate. Without a wild card cert, you might be limited in regards to using sub-domains as per the above examples. Also consider, that you do not have to follow the above examples and only use one domain and use the various ports. 

IMPORTANT: 

  • This does not mean that you have to run the WIFE Server application on a Windows machine to SSL-ify the system; Windows OS was simply used to create this how-to. For the WIFE Server hosted e.g. on Mac OS X, you use right-mouse click and then <Show Package Contents> on the fw Server application package to access its folder structure.
  • “DigiCert” certificate authority (CA) got used simply by chance as an example for this how-to. We don’t specifically recommend them; Comodo, GoDaddy, Symantec, VeriSign etc. basically all work in the same way. It does make sense to use a “global” CA to benefit from them having distributed their root certificates on web browsers and mobile devices.

Working with SSL certificates can be very time consuming. Multitudes of formats, certificate types, file encodings, commands, passwords, misleading or incomplete documentation etc. feed into the complexity of this topic.

Should we ever find the “silver bullet” solution to make it easier to SSL-ify farmerswife … we will do it!

The following steps have been tested and work in real life.

Please also see at the end of this chapter the information on how to correctly upgrade your SSL-ed farmerswife system on Windows/Linux and Mac.

IMPORTANT:

  • Do not copy _any_ commands from this page, because wrong line breaks or white spaces will cause unnecessary errors and failures; you need to manually re-type them in command shells.
  • Also see and use the “Troubleshooting” info at the end of these instructions.

The farmerswife system already uses out of the box 2 built-in self-signed SSL certificates since v5.2 and later. These are the below mentioned “2) server.pem” and “3) skey.pem” files. These two certificates are used for the secured communication between the farmerswife Server and the farmerswife Client application (via default port 22000) and the iOS farmerswife app (via default port 25000).

For practical purposes, you might therefore decide to only focus on SSL-ing the Web Client/Mobile Web Client. You will then be finished after below “Setp c)”.

A completely “SSL-ifyed” farmerswife system uses 3 different SSL “files"!

1) PKCS12 encoded "keystore” file

This is used to create the certificate request, and used by the “Web Client > Port (default port 26000)” for the communication between the farmerswife Server and Web Client / Mobile Web Client. A built-in 3rd party “Jetty” web server powers these, and it’s this Jetty web server, which requires a “keystore” file to be used for the request to the certificate authority (CA).

This “keystore” file should be located within a new manually created “keys” folder here:

farmerswife Server > lib > jetty > keys > keystore

2) server.pem

3) skey.pem

Since version v5.2 built-in self-signed “server.pem” and “skey.pem” are used by default by the “Server Port” (default port 22000) to secure the communication between the WIFE Server and WIFE Client; and the “Api Port” (by default port 25000) for the secure communication between WIFE Server and iOS farmerswife app.

These are located in:

C:\Program Files\farmerswife Server\html_templates\http_session\ssl_certs\..

The below example command line calls assume that you have: 

  •  *.example.org 
  • Organization name: Example Company Ltd.
  • Country: DE
  • All passwords use: secret123
  • You have a “Wild Card” / “*”-level certificate for *.example.org

keytool” is part of your local Java (JRE or JDK) installation; the example paths might differ from the ones you need to use. On Windows you’re looking for “keytool.exe” which is typically located within the Java installation folder:

C:\Program Files\Java\jre_installedversion\bin\keytool.exe

Note: If you launch keytool as per the above path, then your “keystore” file will be created within the same “bin” as the keytool.exe is located.

openssl” is a 3rd party application and part of your farmerswife Server installation on Windows in this path:

C:\Program Files\farmerswife Server\lib\openssl\openssl.exe

Before you start:

Creating and working with SSL certificates can be very time consuming. We recommend that you first apply the below steps on a proper TEST environment. See more “how to” info on any recent farmerswife Release Note’s top section in this chapter “How to run a separate TEST WIFE Server, click on "+" to see the details” (http://farmerswife.com/releasenotes).

  • Quit your WIFE Server application.
  • Search and remove any: server.pem, skey.pem, keys, keystore folders or files on this machine, to avoid confusion. For example you will find a “keystore” file in:
    C:\Program Files\farmerswife Server\lib\jetty\etc\..; but this was shipped together with the built-in 3rd party “Jetty” web server. Simply remove it.
  • Depending on how you use farmerswife and how you implement the SSLed access to the system, you might have to create a file called “server.cfg” within the “system” folder of your farmerswife server installation. This file can be used to override the info in WIFE Server > Setup > General > “Url To Server” field to force-set “https://“. Due to legacy reasons, the “Url To Server” field “normally” only accepts “http://”. This change is only needed for the “correct” link to be created by farmerswife for a “Resource Invitation email” (if used) and for the “Open WebCal Index” page (if used). See the “how to” info on any recent farmerswife Release Note’s top section in this chapter “How to run a separate TEST WIFE Server, click on "+" to see the details” (http://farmerswife.com/releasenotes).

Step a)

Generate your SSL certificate request from the machine running on Windows and hosting the farmerswife Server application.

First create a folder called “keys” in this path:

..\farmerswife Server\lib\jetty\

Then you need to use the command prompt (cmd) in the same directory as the Java "keytool"; keytool.exe is part of any Java installation:

keytool -genkey -keyalg RSA -keysize 2048 -dname "cn=*.example.org, o=Example Company Ltd, c=DE" -alias *.example.org -keystore keystore -keypass secret123 -storepass secret123 -validity 1095

Notes: “validity” here means from “today” up-to/including the day the certificate expires.

==> You now have created the “keystore” file. And you should now see this “keystore” file located within the “bin” folder along this path:

C:\Program Files\Java\jre_installedversion\bin\

Step b)

Create your Certificate Authority request (CA-request).

Now create the CA-request to "Re-Key Your Certificate" (only needed if a wild card *-certificate exists. Otherwise just purchase a new certificate with this CA-reqeust, e.g. a "Standard Single-Name SSL Certificate":

keytool -certreq -alias *.example.org -file star.example.org.txt -keypass secret123 -keystore keystore -storepass secret123

==> You now have your CA-request file "star.example.org.txt" located in:

C:\Program Files\Java\jre_installedversion\bin\

Now log-in to your CA website. The following examples were created using "DigitCert.com" (we don't get any kick-back!). Go to your certificate section and use "Get a Duplicate". Then on the "Get A Duplicate WildCard Certificate (Order #YourOrderNumber" window "Click to upload a CSR” and upload your “star.example.org.txt” file, that way no wrong line breaks or gremlin characters can sneak in.

Then do:
=> Select Your Server Platform: OTHER
=> “Add A Note (Optional)”: SSLing WIFE Server 2017 to 2020
=> "Continue to Next Step" > Process Duplicate WildCard Cert.
=> Once the new certificate is ready, download it in this format: "A single .pem file containing all the certs"      

==> You now have a “star.example.org.pem” file.
This file is needed to finish the "keystore" creation for the Jetty web server.

==> AND: this IS your "server.pem" file; copy and rename "star.example.org.pem" => server.pem.
=> Place the "pem" file in this path:

C:\Program Files\Java\jre_installedversion\bin\

=> and in the command prompt (cmd) launched from the same location as above:

keytool -keystore keystore -importcert -alias *.example.org -file server.pem -trustcacerts -keypass secret123 -storepass secret123

The answer should be:
“Certificate reply was installed in keystore”

==> NOW the “keystore” part is DONE!

Step c)

Change the “jetty.xml” file to use your new SSL-ed “keystore”

Navigate to your farmerswife server installation folder > lib > jetty > etc > ... there are 2 files of interest here:

  • jetty.xml <= this needs to be changed.
  • jetty-ssl.xml <= use the info from here to change the “jetty.xml”.
    IMPORTANT: Use a proper text-editing tool (e.g. Sublime Text 2, TextWrangler, Ultra Edit, etc. etc.). DO NOT copy the text from this solution! The reason: This step c) has caused 99% of support issues due to bad characters, “white space” or “blind spaces” etc. when copying and pasting.

From "jetty-ssl.xml" copy this part (the password info was already changed to match the examples) ... : 

<New id="sslContextFactory" class="org.eclipse.jetty.http.ssl.SslContextFactory">
    <Set name="KeyStore"><Property name="jetty.home" default="." />/etc/keystore</Set>
    <Set name="KeyStorePassword">secret123</Set>
    <Set name="KeyManagerPassword">secret123</Set>
    <Set name="TrustStore"><Property name="jetty.home" default="." />/etc/keystore</Set>
    <Set name="TrustStorePassword">secret123</Set>
  </New>
  <Call name="addConnector">
    <Arg>
      <New class="org.eclipse.jetty.server.ssl.SslSelectChannelConnector">
        <Arg><Ref id="sslContextFactory" /></Arg>
        <Set name="Port">8443</Set>
        <Set name="maxIdleTime">30000</Set>
        <Set name="Acceptors">2</Set>
        <Set name="AcceptQueueSize">100</Set>
      </New>
    </Arg>
  </Call>

... and replace with this part within your “jetty.xml":

<Set name="ThreadPool">
      <!-- Default queued blocking threadpool -->
<New class="org.eclipse.jetty.util.thread.QueuedThreadPool">
        <Set name="minThreads">10</Set>
        <Set name="maxThreads">200</Set>
      </New>
    </Set>
    <!-- =========================================================== -->
    <!-- Set connectors                                              -->
    <!-- =========================================================== -->
    <Call name="addConnector">
      <Arg>
          <New class="org.eclipse.jetty.server.nio.SelectChannelConnector">
            <Set name="host"><SystemProperty name="jetty.host" /></Set>
            <Set name="port"><SystemProperty name="jetty.port" default="8080"/></Set>
            <Set name="maxIdleTime">300000</Set>
            <Set name="Acceptors">2</Set>
            <Set name="statsOn">false</Set>
            <Set name="confidentialPort">8443</Set>
          <Set name="lowResourcesConnections">20000</Set>
          <Set name="lowResourcesMaxIdleTime">5000</Set>
          </New>
      </Arg>
    </Call>

 

By following the above examples you will then have this in your jetty.xml (Important: ensure that you have exchanged "etc" with “keys” and set your passwords):

  <New id="sslContextFactory" class="org.eclipse.jetty.http.ssl.SslContextFactory">
    <Set name="KeyStore"><Property name="jetty.home" default="." />/keys/keystore</Set>
    <Set name="KeyStorePassword">secret123</Set>
    <Set name="KeyManagerPassword">secret123</Set>
    <Set name="TrustStore"><Property name="jetty.home" default="." />/keys/keystore</Set>
    <Set name="TrustStorePassword">secret123</Set>
  </New>
  <Call name="addConnector">
    <Arg>
      <New class="org.eclipse.jetty.server.ssl.SslSelectChannelConnector">
        <Arg><Ref id="sslContextFactory" /></Arg>
        <Set name="Port">8443</Set>
        <Set name="maxIdleTime">30000</Set>
        <Set name="Acceptors">2</Set>
        <Set name="AcceptQueueSize">100</Set>
      </New>
    </Arg>
  </Call>

Step d)

Create your own skey.pem file from your “keystore” file

Feel free to not change the below path; but for this step the “keystore” file was copied to a different location; simply to ensure that the original is not meddled with.

You first need to transform your “keystore” file:

keytool -v -importkeystore -srckeystore keystore -srcalias *.example.org -destkeystore skey.p12 -deststoretype PKCS12

You will get this response; enter your previously set passwords:

Enter destination keystore password: 
Re-enter new password: 
Enter source keystore password: 
 
[Storing skey.p12]

==> Now you have your "private" key, in PKCS12 format called “skey.p12”.

Now create the needed “skey.pem" from the "skey.p12" file by using “OpenSSL”:

C:\Program Files\farmerswife Server\lib\openssl\openssl.exe

In the now opened command prompt use this:

OpenSSL> pkcs12 -in skey.p12 -nodes -nocerts -out skey_nodes_nocerts.pem

You will get this response after entering your previously set password:

Enter Import Password:

 MAC verified OK

... and now rename “skey_nodes_nocerts.pem” => “skey.pem”

==> You now have your skey.pem file.

Step e)

Final changes on various files and settings:

Implement your “skey.pem” and “server.pem”

Copy the “skey.pem” file from above “Step d)” and the “server.pem” file from above “Step b)” to this folder location:

farmerswife Server > html_templates > http_session > ssl_certs > ..

In farmerswife Server > Setup > General tab, ensure these two settings are correctly set:

“Url To Server” field for "example.org" … “but I need https://!”

Ensure that you have entered the correct external public static IP or domain name into the "Url To Server" field.

This needs to be reachable from outside of your network and correctly port forwarded to the machine hosting the farmerswife server application and was used to create the keystore file and CA request.


IMPORTANT: 
The field "Url To Server" within the fw Server's Setup is used for two fw Client desktop application features: 

- "Web Access Invite emails" for Contact types Client and Resource.

- "Open WebCal Index" via fw Client desktop app > Menu > Open WebCal Index, or left-mouse-click on Hourline icon > Open WebCal Index, or by using the correct url.

This means, that there is only one fw Server-side field (i.e. "Url To Server") to cater to two different sets of functionality, which also each use their own port.

The examples here use in fw Server > Setup > General > Legacy HTTP Settings > "Url To Server" field this domain name for the "Web Client Port":

http://fw-web.example.org

Here once more, but now the shortened overview of the 3 approaches to SSLify your fw system by using your own certs:

fw Server Port settings name

SSLed by default

URL / DNS with re-direction

fw Server Port value on DemoDB

1) SSLify the fw Server app without redirection

2) “Proxy WIFE Server” mode on DMZ

3) “Proxy” port values

Web Client Port
-
fw-web.example.org

26000 ****

(HTTP)

443 ****
26000 or 443 via own DNS ****
443  via own DNS ****
Mobile Web Client
-
fw-mobile.example.org

26000 ****

(HTTP)

443/mobile ****
26000 or 443 via own DNS ****
443 via own DNS ****
Legacy Http Port
-
fw-webcal.example.org

27000

(HTTP)

27000
27000 or 443 via own DNS
443 via own DNS +*****


**** Since v6.0 it's possible to control whether the Web Client Port is automatically added to the URL defined in "Url To Server".
Among other things, it's used for building the invitation links that are sent through email to certain new web client users.
The problem was that it automatically appended the Web Client's Port to the URL. And that didn't work well if you wanted to run the Web Client on one port (for example 26000), but use the firewall or a proxy to route from another port (for example 443) to it. The invitation emails would always have port 26000 in them.

Now you can just go to fw Server Setup > General > Legacy HTTP Settings and click the little pop-up menu and un-check "Automatically Add Web Client Port To 'Url To Server'".


And there is more:
Due to legacy reasons, the field “Url To Server” only accepts url-strings beginning with “http://”.
The LEGACY "SSL Port" (<= DO NOT USE!) took care of this for certain legacy features, by adding the "https://". We plan to clean this up in the future, so please do not use the legacy "SSL Port" field!
As already mentioned at the beginning of this how-to, depending on how you use farmerswife and how you implement the SSLed access to the system, you might have to create a file called “server.cfg” within the “system” folder of your farmerswife server installation.
This “server.cfg” file can be used to override the info in WIFE Server > Setup > General > “Url To Server” field to force-set “https://“. The field “Url To Server” is called “HTTP_HOME” within the “server.cfg” file.

IMPORTANT: Once more, the above described use of the server.cfg file is only needed for the “correct” link to be created by farmerswife for the “Open WebCal Index” page (if used) and for the "Web Access Invite emails" for Contact types Client and Resource (if used).
Creating and using the “server.cfg” files is explained in the “how to” info on any recent farmerswife Release Note’s top section in this chapter: “How to run a separate TEST WIFE Server, click on "+" to see the details” (http://farmerswife.com/releasenotes).

“Web Client > Port” … for: 443

Make sure that you have here entered the correct port for the “Web Client > Port” which is reachable from outside your network and correctly port forwarded to the machine hosting the farmerswife Server application and was used to create the keystore file and CA request.

If you are already using the “server.cfg” file (see above info), you might as well change here that the “Web Client > Port” value is correctly set to use 8443; the “Web Client > Port” is called ”WEBCLIENT20_PORT” within the “server.cfg” file.

Step f)

Test your SSL-ed farmerswife system

Start your farmerswife Server.

Once it’s up and running and the Jetty web server has finished to launch itself and Java (see in the WIFE Server’s Log window “farmerswife New Web Server Started (PID: xxxx)”) try to log-in via:

  • farmerswife Client application
  • iOS farmerswife app
  • Web Client
  • Mobile Web Client

Ideally you’re able to log-in from within your local area network (LAN), but also from outside of your LAN.

Troubleshooting:

The above-described approach is one of many ways on how to SSL-ify your farmerswife system.

Even if you don’t deviate from the above approach, you might encounter problems, which are specific to your environment, to your SSL certificate, etc.

Use your farmerswife server’s “log” files:
farmerswife Server > system > log.txt

This is the main log file of your WIFE Server; oldest information is listed at the top. Here you will see issues in regards to the WIFE Client application and iOS farmerswife app when logging into your WIFE Server.

Use your Jetty web server’s “log” files: 
farmerswife Server > lib > jetty > logs > yyyy_mm_dd.stderrout.log

These "*.stderrout.log" files (and some more, not so relevant ones) are created by your WIFE Server’s built-in 3rd party “Jetty" web server; here you will find information in regards to issues when logging into the Web Client and Mobile Web Client.

How to upgrade your SSL-ed farmerswife system

The upgrade procedure as such is the same as always, except that you now have a couple of “customized files” which you need to take special care of.

First ensure you have backed up all related files.

For example create a folder on the Desktop of the WIFE Server host machine, and call it “farmerswife SSLed backup yyyy-mm-dd”, containing these files:

  • jetty.xml
  • keystore
  • server.pem
  • skey.pem

And after the upgrade, please ensure that access with all “clients” works (farmerswife Client software, iOS farmerswife app, Web Client and Mobile Web Client).

On Windows/Linux:
Change the file properties to “Read Only” on:

farmerswife Server > html_templates > http_session > ssl_certs >
                server.pem
                skey.pem

farmerswife Server > lib > jetty > etc >
                jetty.xml

Note: you don’t need to do this on the “keystore” file, since it is in a location, which is not touched by the install process.

Then on upgrading your farmerswife server using the Install Wizard on Windows, simply click on “Ignore” on the “read only warning” pop-up message during the installation process.

On Mac:

The upgrade process on Mac, requires you to manually copy and paste the needed files into the “NEW” farmerswife server package. Either copy them from within the “OLD” farmerswife server package to the “NEW” one.
Or you copy them from the above-mentioned “backup” folder on your Desktop to the correct paths in the “NEW” farmerswife server package.

On the “NEW” farmerswife Server package > do <Control> + click and select “Show Package Contents”, then copy and replace in:
> html_templates > http_session > ssl_certs >
                server.pem
                skey.pem

> lib > jetty > etc >
                jetty.xml

> lib > jetty > keys >
                keystore

Internet links used to create and test this how to:
https://wiki.eclipse.org/Jetty/Howto/Configure_SSL#Password_Issues
http://docs.activestate.com/activetcl/8.6/tls/tls.html
https://www.openssl.org/docs/HOWTO/certificates.txt
https://support.ssl.com/Knowledgebase/Article/View/19/0/der-vs-crt-vs-cer-vs-pem-certificates-and-how-to-convert-them

Not so useful:
https://www.digicert.com/ssl-support/pem-ssl-creation.htm

Misc:
https://www.openssl.org/docs/apps/rsa.html
https://polarssl.org/kb/cryptography/asn1-key-structures-in-der-and-pem
http://www.cryptosys.net/pki/rsakeyformats.html

A big THANK YOU to:
Linus, Søren, Nicolaj, Henrik, Michael, David

Use the “Proxy WIFE Server” mode on a DMZ-hosted machine

The fw Server application can also be run in a so called “Proxy WIFE Server” mode. This is a special mode, which does NOT require actual license files and it does not store information within a database.

The “Proxy WIFE Server" will then be run from it’s own host machine within your DMZ (DeMilitarized Zone). The "Access Tiers" (iOS farmerswife app, Web Client, Mobile Web Client, WebCal Event subscriptions, etc.) then connect to this “Proxy WIFE Server” via their “normal” Ports. The “Proxy WIFE Server” itself only communicates through a single Port to the real “master” WIFE Production Server, which is run from inside your local network (LAN) behind the firewall.
The fw Client desktop application is not intended to connect directly to the "Proxy WIFE Server". You can either use a VPN solution for a direct and secure connection to the WIFE Production Server from outside of your LAN, or use the IP or domain name of the machine hosting the Proxy WIFE Server, since the Port to the “master” WIFE Production Server is the same one used by the Proxy WIFE Server and all fw Client applications.

This functionality is available since farmerswife version 5.0.

Setup and Configuration

IMPORTANT: No license files are needed by design to run the Proxy WIFE Server.

Since v5.2 you’ll need to set-up a user to be used by the Proxy WIFE Server. This is needed, because since v6 the Proxy WIFE Server also needs to authenticate itself with your “master” WIFE Production Server due to the "out of the box" self-signed certificate SSLed connection. We recommend creating a new “Web User" with it’s own Web Permission Profile where everything is turned OFF except in "Allowed Access Tiers > Dispatch Access Through Desktop Client" is enabled/ticket, and with a password which is used in no other place. You can request a “Proxy WIFE dedicated Web User” free or charge by referencing this document from support@farmerswife.com. This free-of-charge licensed Web User must never be used by anything else but the "Proxy WIFE Server"; otherwise we will be forced to remove it from your license again.

The Proxy WIFE Server is an independent farmerswife Server installation on a machine residing within your DMZ.

The same system requirements apply as for a Production WIFE Server. For example you'll also need to install "Java" (JRE on Windows and JDK on Mac), for the built-in Jetty web-server to work.

The Proxy WIFE Server has to be manually upgraded, to always be on the same version as the “master” Production WIFE Server.

The Proxy WIFE Server can be “SSLed” in the same way as the standard farmerswife Server application.

On Windows:

  • Install a WIFE Server as usual using the same installer version currently running on your Production WIFE Server.
  • Ensure to create a Desktop icon while installing!
  • IMPORTANT: Do NOT run/launch it at the end of the installation process from the installer wizard, i.e. remove the checkbox on the “Launch Farmers WIFE Server” option on the last page of the installer wizard.

    VERY IMPORTANT: When you upgrade the Proxy WIFE Server hosted on Windows, you always have to remember to remove the checkbox on the “Launch Farmers WIFE Server” option on the last page of the installer wizard. You always have to start the Proxy WIFE Server from the specially prepared Desktop link explained in the next step! 
  • Go to the Desktop icon, right-mouse click on it and select “Properties”. In the “Target” field type: –proxy after the target’s path, e.g. like this: “…\Farmers WIFE Proxy Server\Farmers WIFE 64bit.exe” –proxy.
  • Now start the Proxy WIFE Server for the 1st time ONLY by using this special desktop shortcut.  After it has started you will see “Failed to connect to the master Server”. Therefore Quit it by using the “x” button in the top right corner. This first start-up creates the “system” folder within the root installation folder of your Proxy WIFE Server installation.
  • Go to the “system” folder residing within the root installation folder of the Proxy WIFE Server.
  • Edit the file proxy_settings.xml to configure it according to your needs, see details on next page.

Then start the Proxy WIFE Server again by using the special desktop link. The “proxy_settings.xml” file is explained further down below.

On Mac:

  • Install a WIFE Server as usual using the same installer version currently running on your Production WIFE Server.
  • Rename the WIFE Server package, e.g. to “PROXY farmerswife Server InstalledVersionNumber revxxx”.
  • Create an empty file called “proxy_settings.xml” (or request it from support@farmerswife.com).
  • Use “Show Package Contents” on the PROXY farmerswife Server package, create a folder called “system”, place the “proxy_settings.xml” into the just created system folder; see more info on next page.
  • Now start the PROXY Server for the 1st time.  After it has started you will see “Failed to connect to the master Server”. Therefore Quit it by using the “x” button in the top left corner. This first start-up will now have populated the needed data within the proxy_settings.xml
  • Edit the file proxy_settings.xml to configure it according to your needs. Then start the Proxy WIFE Server again. The proxy_settings.xml is explained next.

Configuring the proxy_settings.xml file

The proxy_sttings.xml file is the place to configure the four Ports supported by the Proxy WIFE Server. It looks like this:

<?xml version="1.0" encoding="utf-8"?>
<ProxyServerSettings>
<LEGACY_HTTP_PORT>27000</LEGACY_HTTP_PORT>
<LEGACY_HTTP_SSL_PORT>22010</LEGACY_HTTP_SSL_PORT
<LEGACY_HTTP_USE_SSL_PORT>0</LEGACY_HTTP_USE_SSL_PORT>
<WEBCLIENT_PORT>26000</WEBCLIENT_PORT>
<API_PORT>25000</API_PORT
<ADDRESS_INTO_MASTER_WIFE_SERVER>192.168.1.1</ADDRESS_INTO_MASTER_WIFE_SERVER
<PORT_INTO_MASTER_WIFE_SERVER>22000</PORT_INTO_MASTER_WIFE_SERVER
<WIFE_USER_LOGIN>proxy</WIFE_USER_LOGIN
<WIFE_USER_PASSWORD>PasswordUsedNoWhereElse</WIFE_USER_PASSWORD>
</ProxyServerSettings>

Simply edit the values for the ports according to your desired configuration and save this file.

Note: Once done inform your farmerswife users, on how to connect to the now proxied system.

To know more about the above mentioned Ports, use the “Server Ports and Access Tiers” info from our open Knowledgebase (https://support.farmerswife.com).

Once the  proxy_settings.xml file is correctly configured, and you have successfully launched the Proxy WIFE Server, it will connect to the “master” WIFE Production Server via the main “Server Port” (typically Port value 22000).

Troubleshooting the "Proxy WIFE Server"

Within it's "system folder you'll find the "proxy_log.txt" file. This file only logs information about it's "runtime".  Users accessing your farmerswife system are all logged on your "Production WIFE Server" log.txt as before.

When the "Production WIFE Server" does it's "Nightly Forced Shutdown", the "Proxy WIFE Server" obviously looses it's connection.
And once a connection has been established again, it will restart itself.
The minute based checker states in the Proxy WIFE Server's Log Window:

=> PIDnumber:yyyymmmdd: hh:mm: Master Server OK

On "Lost Connection to Master... Retrying" (e.g. this will also take place during the "nightly forced shutdown" of the fw Master Server) this will happen:
...
2956: 20170530:1249:Master Server OK
2956: 20170530:1250:Master Server OK
2956: 20170530:1251:Lost Connection to Master... Retrying
2956: 20170530:1251:Force Server Shutdown - Restart = 1
2956: 20170530:1251:farmerswife New Web Server Stopped
2956: 20170530:1251:Stopping farmerswife Client Server
2956: 20170530:1251:Stopping Watchdog
2956: 20170530:1251:Starting New Server Instance

INIT
3840: 20170530:1251:Running: farmerswife Server 6.3 (Nightly Build - 30/05/2017) (Rev: 16833) 64bits
3840: 20170530:1251:Running on: Windows Server 2012 R2 Standard (amd64 64 bits)
3840: 20170530:1251:Process ID (PID): 3840
3840: 20170530:1251:Loading Graphics
3840: 20170530:1251:Checking License
3840: 20170530:1251:IP: 192.168.1.1 
3840: 20170530:1251:Starting Proxy Server
3840: 20170530:1251:Reading proxy settings from proxy_settings.xml
3840: 20170530:1251:Read XML: <?xml version="1.0" encoding="utf-8"?>
<ProxyServerSettings>
<LEGACY_HTTP_PORT>27000</LEGACY_HTTP_PORT>
<LEGACY_HTTP_SSL_PORT>22010</LEGACY_HTTP_SSL_PORT>
<LEGACY_HTTP_USE_SSL_PORT>0</LEGACY_HTTP_USE_SSL_PORT>
<WEBCLIENT_PORT>55005</WEBCLIENT_PORT>
<API_PORT>25000</API_PORT>
<ADDRESS_INTO_MASTER_WIFE_SERVER>192.168.1.1</ADDRESS_INTO_MASTER_WIFE_SERVER>
<PORT_INTO_MASTER_WIFE_SERVER>55000</PORT_INTO_MASTER_WIFE_SERVER>
<WIFE_USER_LOGIN>proxy</WIFE_USER_LOGIN>
<WIFE_USER_PASSWORD>PasswordUsedNoWhereElse</WIFE_USER_PASSWORD>
</ProxyServerSettings>
 
3840: 20170530:1251:Proxy Setting LEGACY_HTTP_PORT : 27000
3840: 20170530:1251:Proxy Setting LEGACY_HTTP_SSL_PORT : 22010
3840: 20170530:1251:Proxy Setting LEGACY_HTTP_USE_SSL_PORT : 0
3840: 20170530:1251:Proxy Setting WEBCLIENT_PORT : 55005
3840: 20170530:1251:Proxy Setting API_PORT : 25000
3840: 20170530:1251:Proxy Setting ADDRESS_INTO_MASTER_WIFE_SERVER : 127.0.0.1
3840: 20170530:1251:Proxy Setting PORT_INTO_MASTER_WIFE_SERVER : 55000
3840: 20170530:1251:Proxy Setting WIFE_USER_LOGIN : proxy
3840: 20170530:1251:Proxy Setting WIFE_USER_PASSWORD : proxy
3840: 20170530:1251:Writing proxy settings to proxy_settings.xml
3840: 20170530:1251:Trying to connect to the master server. address: 127.0.0.1 port: 55000
3840: 20170530:1251:Failed to connect to the master server
3840: 20170530:1251:Trying to connect to the master server. address: 127.0.0.1 port: 55000
3840: 20170530:1251:Failed to connect to the master server
3840: 20170530:1251:Trying to connect to the master server. address: 127.0.0.1 port: 55000
3840: 20170530:1251:Failed to connect to the master server
3840: 20170530:1251:Trying to connect to the master server. address: 127.0.0.1 port: 55000
3840: 20170530:1251:Failed to connect to the master server
3840: 20170530:1252:Trying to connect to the master server. address: 127.0.0.1 port: 55000
3840: 20170530:1252:Failed to connect to the master server
3840: 20170530:1252:Trying to connect to the master server. address: 127.0.0.1 port: 55000
3840: 20170530:1252:Failed to connect to the master server
3840: 20170530:1252:Trying to connect to the master server. address: 127.0.0.1 port: 55000
3840: 20170530:1252:Failed to connect to the master server
3840: 20170530:1252:Trying to connect to the master server. address: 127.0.0.1 port: 55000
3840: 20170530:1252:Failed to connect to the master server
3840: 20170530:1252:Trying to connect to the master server. address: 127.0.0.1 port: 55000
3840: 20170530:1252:Failed to connect to the master server
3840: 20170530:1252:Trying to connect to the master server. address: 127.0.0.1 port: 55000
3840: 20170530:1252:Failed to connect to the master server
3840: 20170530:1252:Trying to connect to the master server. address: 127.0.0.1 port: 55000
3840: 20170530:1252:Connected to the master server
3840: 20170530:1252:Found JRE version 1.8.0_91
3840: 20170530:1252:farmerswife New Web Server Starting (55005)
3840: 20170530:1252:Opening API Port (25000)
3840: 20170530:1252:Starting Heartbeat To Server: 127.0.0.1 port: 55000 ; every 60 secs
3840: 20170530:1252:Master Server OK
3840: 20170530:1253:farmerswife New Web Server Started (PID: 3336)
3840: 20170530:1253:Master Server OK
3840: 20170530:1254:Master Server OK

...

Use a “Proxy” to apply your SSL certificates

This chapter is still work in progress.
And please note, that certain needed functionality for this to work as described here, will require to be running on not yet released version v6.4 (planned during Q2 2018)
As soon as it's ready, we'll be adding the complete example config file on "this is how we implemented this by using "NGINX".

Use a freshly installed computer; e.g. a Linux Debian.
Create a "key pair" private-public certificate that matches the DNS-records as per the above examples or per your desired configuration.

The API Port, Web Client Port (also used by the Mobile Web Client) and the Legacy HTTP Port are using HTTP protocol. They can all be “proxied” from the same port (for example “443”). The Server Port and Filetransfer Port use TCP streams over SSL/TLS and they should be proxied as they are. See the table at the beginning of this article. 

The File Transfer Port cannot yet be configured to support a "proxy configuration". With v6.4 rev. 16890 there is a new fw Server side setting for the File Transfer Port, which allows to set the correct fw Client side “proxied filetransfer port” by using above example Port: 8080.
NOTE: the auto-fwClient upgrade functionality will only work, if the fw Client has successfully logged into the fw Server with right Proxy File Transfer Port settings in place. Or, the fw client simply needs to be manually upgraded.

We are still working on improving this section. Please check back into this solution by end of July 2018.


Last updated: 15. June 2017

Did you find it helpful? Yes No