IMPORTANT:
- This article is targeted at IT admins!
- SSLing of the built-in Jetty web server has changed with the Release of v6.8!
- Ensure you have "OpenJDK" HotSpot v11 installed on your host machine, more info here.
- Do not copy from this solution article, as it may introduce wrong characters on your side, due to potentially hidden characters!
- Also: information in this article was publicly available and should not get used on your side, i.e. use a different password than in our example!
The farmerswife (fw) Server app uses two different sets of certificates:
The farmerswife system gets shipped, with the fw Server app being deployed with our own self-signed certificates. These are only used for the communication between the fw Client desktop app and the iOS fw app with the fw Server app.
These self-signed certificates are not in use for the Web Client and Mobile Web Client, as this would lead to complications because your web browser would still complain about the connection not being secure due to self-signed certs being in use.
This article explains how you can implement your own SSL certs for your farmerswife Web Client and Mobile Web Client, as well as how to exchange our self-signed certs with your own for the fw Client desktop app and the iOS fw app.
You can achieve "SSLing farmerswife" using two different approaches:
- SSLing your actual farmerswife Server app (this is covered here), or
- by using a third party service as proxy, e.g. using NGINX as the third-party service (covered here).
By default farmerswife uses a set of five different ports, three of them using HTTP protocol, and the other two only using TCP.
- Server Port: 22000 TCP over TLS by default *
- File Transfer Port: 24000 TCP
- iOS fw app / API Port: 25000 XML over HTTPS *
- Web Client (& Mobile Web Client ) > Port: 26000 HTTP
- WebCal / HTTP Port: 27000 HTTP
* Using the self-signed certificate by default.
SSLing your farmerswife server
In order to be able to apply your own SSL certs to farmerswife you need the certificate.crt and certificate.key of your system domain/subdomain. Below you will see an example of how they start and finish:
certificate.crt:
-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----certificate.key:
-----BEGIN PRIVATE KEY-----
-----END PRIVATE KEY-----More on "optioning" your SSL certs
If you don't have any certificate at all yet:
Choose your Certificate Provider or Certificate Authority (CA).
Follow the instructions of YOUR CA on how to create a Certificate Signing Request (CSR) from the host machine of the fw server app. This will make it later possible, to export the private key.
For a manual CSR ... go here:
Due to recent support cases, here the "solution article" from DigiCert (no affiliation):
https://www.digicert.com/support/tools/certificate-utility-for-windows
SSLing your Web Client and Mobile Web Client
Step 1:
On Windows:
Place a copy of your certificate.crt and certificate.key inside the following folder located inside your farmerswife Server app installation, typically in: C:\Program Files\farmerswife Server\lib\openssl\..
On macOS:
Since "LibreSSL" is pre-installed on macOS; "openssl" commands work just fine. Create a folder, place the copy of certificate.crt and certificate.key inside and start the following commands in Terminal from this folder.
On Linux Ubuntu:
Ensure "OpenSSL" is installed. Create a folder, place the copy of certificate.crt and certificate.key inside and start the following commands in Terminal from this folder.
Step 2:
Execute the following command to start creating a keychain:
Windows: C:\Program Files\farmerswife Server\lib\openssl>openssl.exe pkcs12 -export -name servercert -in certificate.crt -inkey certificate.key -out myp12keystore.p12
macOS and Linux Ubuntu: openssl pkcs12 -export -name servercert -in certificate.crt -inkey certificate.key -out myp12keystore.p12
You will be asked to set a password for your certificate chain, which will be needed on the next step and for the configuration of the bundled-in web server.
Step 3:
Once done you have to copy the file myp12keystore.p12 to the following folder:
On Windows: C:\Program Files\Java\jre_installedversion\bin\
macOS and Linux Ubuntu: Simply move on to the next step.
Now execute the following command:
On Windows: C:\Program Files\Java\jre_installedversion\bin>keytool.exe -importkeystore -destkeystore keystore -srckeystore myp12keystore.p12 -srcstoretype pkcs12 -alias servercert
macOS and Linux Ubuntu: keytool -importkeystore -destkeystore keystore -srckeystore myp12keystore.p12 -srcstoretype pkcs12 -alias servercert
IMPORTANT: Remember which password you used in this step, as it will be needed for configuring the SSL on the web / mobile client.
Step 4:
Now grab the file named keystore and move it to the following folder:
On Windows: C:\Program Files\farmerswife Server\lib\jetty\etc\
On macOS: /path/to/your/farmerswife Server/Contents/lib/jetty/etc/
On Linux Ubuntu: /path/to/your/farmerswife Server/lib/jetty/etc/
NOTE: The "lib > jetty > etc" folder already contains the default "jetty-created" keystore file. You are going to over-write / replace this file with your own keystore file!
VERY IMPORTANT:
On Windows: Set this keystore file as "Read Only" and ensure you have a safe copy of this keystore file!
When upgrading the fw Server app to a new version, ensure you use the "Ignore" option when the Installation Wizard stops on this Read Only file, to NOT overwrite this file!
On macOS and Linux Ubuntu: ensure you have a safe copy of this keystore file! And after the upgrade, ensure you are copying it back into the new fw Server app package.
Step 5:
You now need to edit the "start.ini" file located ...
on Windows: C:\Program Files\farmerswife Server\lib\jetty\
on macOS: /path/to/your/farmerswife Server/Contents/lib/jetty/
on Linux Ubuntu: /path/to/your/farmerswife Server/lib/jetty/
... in two places:
a) in line 159 change this:
--module=http
... to disable it, by changing it to this:
# --module=http <= YourInitials disabled to make new SSLing work yyyy-mm-dd.
b) after line 205, where you see this:
--module=rewrite
... you need to add this info and adapt it as per your own configuration above:
# YourInitials added below to make new SSLing work. yyyy-mm-dd
--module=https
jetty.sslContext.keyStorePath=etc/keystore
jetty.sslContext.keyStorePassword=YourOwnPW
jetty.sslContext.keyManagerPassword=YourOwnPW
jetty.sslContext.trustStorePath=etc/keystore
jetty.sslContext.trustStorePassword=YourOwnPW
jetty.ssl.port=443
--module=ssl-reload
etc/jetty-https.xml
etc/jetty-ssl.xml
etc/jetty-ssl-context.xml
etc/jetty-ssl-context-reload.xml
etc/tweak-ssl.xml
VERY IMPORTANT:
On Windows: Set this start.ini file as "Read Only" and ensure you have a safe copy of this start.ini file!
When upgrading the fw Server app to a new version, ensure you use the "Ignore" option when the Installation Wizard stops on this Read Only file, to NOT overwrite this file!
On macOS and Linux Ubuntu: ensure you have a safe copy of this start.ini file! And after the upgrade, ensure you are copying it back into the new fw Server app package.
Step 6:
Download this "tweak-ssl.xml" file at the bottom of this article (this is used to prevent cross-side-scripting hacks) and place it in this location:
On Windows: C:\Program Files\farmerswife Server\lib\jetty\etc\
On macOS: /path/to/your/farmerswife Server/Contents/lib/jetty/etc/
On Linux Ubuntu: /path/to/your/farmerswife Server/lib/jetty/etc/
SSLing your fw Client desktop app / iOS fw app access:
Step 1:
Copy your certificate.crt and certificate.key to the following folder:
On Windows:
C:\Program Files\farmerswife Server\html_templates\http_session\ssl_certs\
On mac and Linux Ubuntu:
/path/to/your/farmerswife Server/html_templates/http_session/ssl_certs/
Step 2:
Rename the already existing server.pem and skey.pem to server.pem.old and skey.pem.old in order to rename:
certificate.crt to server.pem
and certificate.key to skey.pem
VERY IMPORTANT:
On Windows: Set both of these files "server.pem" and "skey.pem" as "Read Only" and ensure you have a safe copy of them!
When upgrading the fw Server app to a new version, ensure you use the "Ignore" option when the Installation Wizard stops on these Read Only files, to NOT overwrite these files!
On macOS and Linux Ubuntu: ensure you have a safe copy of these "server.pem" and "skey.pem" files! And after the upgrade, ensure you copy them back into the new fw Server app package, to replace the ones that are already there.
Modifying farmerswife server config to add https to the URL’s
To automatically add "https" to the URL’s generated by the farmerswife server you need to add one parameter to the server through the optional file "server.cfg", which must be located inside the "system" folder of your farmerswife Server app installation:
Windows: C:\Program Files\farmerswife Server\system\
Mac and Linux: /path/to/your/farmerswife Server/system/
Get more info from here on how to work with the optional "server.cfg" file. On this file you need to modify the following variable to contain the correct domain name used for your certs:
HTTP_HOME https://farmerswife.example.com
This optional configuration file has to be used, instead of the Server app Setup > Gneral tab field “Url To Server”; since this field will only accepts URL strings beginning with “http://” due to legacy reasons.
Troubleshooting
In case something fails during the process please check the following logs, the following are the logs of the farmerswife server application:
Windows: C:\Program Files\farmerswife Server\system\log.txt
Mac and Linux: /path/to/your/farmerswife Server/system/log.txt
And this one is for the web / mobile web server:
Windows: C:\Program Files\farmerswife Server\system\web_logs\yyyy_mm_dd.stderrout.log
Mac: /path/to/your/farmerswife Server/Contents/system/web_logs/yyyy_mm_dd.stderrout.log
Linux: /path/to/your/farmerswife Server/system/web_logs/yyyy_mm_dd.stderrout.log
How to upgrade your SSLed farmerswife system
Before upgrading your farmerswife server you will need to make a backup of the following files:
- start.ini
- keystore
- server.pem
- skey.pem
The reason is that the server installation process for the upgrade will overwrite those files, so after the upgrade you just need to copy the backup in its original place.
On mac you will need to manually copy those files together with your system folder to the new server application downloaded.