Linx Application Server Configuration Management and Common Issues

Additional Server Configuration

To enable Linx Application Server to send server related emails (e.g. password resets) edit the configuration file located at:

C:\Program Files (x86)\Twenty57 Linx Server 5\Bin\Server\Twenty57.Linx.Server.Core.exe.config

Add the below SMTP settings to the config file’s app settings:

<appSettings>

<add key="SmtpHost" value="my-smtp-server.com"/>

<add key="SmtpPort" value="587"/>

<add key="SmtpFromEmailAddress" value="linx@domain.com"/>

<add key="SmtpUserName" value="user-name"/>

<add key="SmtpPassword" value="my-smtp-password"/>

</appSettings>

Note: In the Windows Local Services Manager, once you have edited the config file and saved it, restart the ‘Linx Server 5’ local service.

Getting Past Size Limitations of REST WebServices

We’ve been receiving some issues with size limitation on Web Services. Two specific scenarios:

  • Receiving Large requests
  • Sending Large responses

Errors that were received included “413 (Request Entity Too Large)” or “Response over configured buffer size”.

To fix this, there are 3 sets of configurations that needs to be done. The first is to solve the 413 error, and that is to configure the computer itself to receive larger files. This post explains the steps: http://blogs.catapultsystems.com/rhutton/archive/2012/07/22/request-entity-is-too-large-over-ssl-in-iis-7/1 or you can just use this in CMD.exe:C:\Windows\SysWOW64\inetsrv\appcmd.exe set config -section:system.webServer/serverRuntime /uploadReadAheadSize:“20480000” /commit:apphost

And also, there’s some configurations you can set in the “C:\Program Files (x86)\Twenty57 Linx 5\bin\Twenty57.Linx.Server.Core.exe.config”:
You’ll need to play with the numbers a bit.

<appSettings>

<add key="WebServerPort" value="8022"/>

<add key="WCFSendTimeoutSeconds" value="60" />

<add key="WCFReceiveTimeoutSeconds" value="600" />

<add key="WCFMaxReceivedMessageSizeBytes" value="20485760" />

<add key="WCFMaxStringContentLengthCharacters" value="2000000" />

<add key="WCFMaxFaultSizeBytes" value="128536" />

</appSettings>

Lastly, the RESTWebService component has got some settings one can set (Check the help of the control):
image

SSL and Linx Application Server

To secure your Linx solutions and set up your Linx Server to the correct ports on your server, you’ll need to work with SSL Certificates. Linx Server already contains an SSL certificate, which is valid and secure, but because it is self signed it may not be accepted in certain situations.

SSL Certificates use two keys which are long strings of seemingly randomly generated numbers. One is called a private key and one is called a public key. A public key is known to your server and available in the public domain. It can be used to encrypt any message. The private key is needed to decrypt the message. Thus, even if a message is intercepted, it cannot be decrypted without the private key.

Depending on you solution, Linx uses these Certificates in multiple ways, sometimes playing the role of Server (having both the public and private keys) and sometimes being a Client / Consumer (only with the public key).

Some key areas where you’d want to create or obtain an SSL certificate for your Linx solution:

  • Linx Server (It comes with an SSL certificate already, but in some organisations, they require their own certificates to be used)
  • REST and SOAP Web services
  • FTP Authentication
  • Web hooks

Here’s how to create and use a self-signed SSL certificates with Linx:
1. Create your own certificate (skip this step if you’re getting a certificate from a Certificate Authority or from your IT Security team)
Note: This certificate is called a “Self signed certificate” which means it was not issued through a recognised Certificate Authority, but it still secures and encrypts your data. Your web browser will complain about the legitimacy of the certificate, but as you’ve created the certificate yourself, you can ignore the warning.

  • Download the appropriate version of OpenSSL for your version of Windows from: http://slproweb.com/products/Win32OpenSSL.html 1
    The light version (3Mb) will suffice.

  • Install the version and make a note of the directory where you are installing as you will need it later. If you get the option to choose, install the “bin” folder in the application’s own folder.

  • Open Command Prompt

  • Navigate to the /bin directory in the OpenSSL install directory (eg “cd C:\OpenSSL-Win64\bin”).

    To generate a private key called “sslprivatekey” run the following command:

    openssl genrsa -out sslprivatekey.pem 1024

    To create an X509 certificate (.cer file) containing your public key run the following command:

    openssl req -new -x509 -key sslprivatekey.pem -out sslpublickey.cer -days 1825

    You will be prompted to complete several fields. The information provided will then be incorporated into your certificate request. To leave a field blank, simply enter ‘.’

    To export your x509 certificate and private key to a pfx file. run the following command (take note of the friendly name given):

    openssl pkcs12 -export -out sslpublic_privatekey.pfx -inkey sslprivatekey.pem -in sslpublickey.cer -name “LinxTestCert”

    You will be prompted to enter your Export password and confirm it. Make a note of your password as you will need it later.

    To import this key into your system for Linx to use, double click on the PFX file and select import.

2. Now you’ll have an SSL Certificate (with a private key) installed on your system. You need to obtain it’s thumbprint (you don’t need to obtain the thumbprint if you are going to use Powershell to bind the certificate to the ports as described below in the next section.):

Click on your start button and type in “Certificate”. Choose an option like “Manage computer certificates”

Find your new certificate, normally under the Personal, Certificates heading, and double click on it

On the details tab, find your certificate’s “Thumbprint”. Click on it and copy the whole string in the box. This code uniquely identifies the certificate on your system.

VERY IMPORTANT : When copying the thumbprint for a certificate, there are almost always a hidden character in front of the certificate. Notepad cannot show this character, use a more advanced text editor with the option to show hidden characters. You can also change the Text encoding to “ANSI” which will show the hidden character immediately. Delete these characters and all the spaces.

You should now have something which resembles a long string of numbers and letters. Keep this safe for now.
(i.e. 397a5f046b5c82db948ddcf55c7ccf1af8708ae5)

3. Linx Application Server
When using Linx Application Server, you’ll notice that your browser will complain about the privacy of your connection. You can check the certificate used by default and see that it was issued by Twenty57. Although we know that the connection is secure, the browser cannot confirm the authenticity of the current certificate, and as such must give the user a warning. In some circumstances you would need to correct this issue, especially in production systems.

To set up a different certificate, you’ll need to bind your new certificate to the port you are using with Linx Application Server.

There are 2 ways to bind the certificate, through 1. Command Prompt , or through 2. Powershell .
1. Binding a certificate with Command Prompt (Longer route):

Run Command Promt (with Administrator rights)

Using the thumbprint you obtained in the previous steps, use the following command, all in one line (Note the port number, you can change it to whatever port you need, and add your thumbprint for the certhash):

netsh http add sslcert ipport=0.0.0.0:9023 certhash=d7bd8d21761135c12249cb1467a5caed6c6efc07 appid={00000000-0000-0000-0000-000000000000}

Restart your Linx Service

If needed you’ll have to open up the port in Windows Firewall to allow access to your Linx Application Server from outside of the machine.

2. Binding a certificate with Powershell:

Create a script (i.e. BindPort.ps1 file) with the following (Change the port numbers and Certificate Friendly name):

#open the port on the windows firewall - Change Port Number here
New-NetFirewallRule -Name “Linx Api” -DisplayName “Linx Api” -Enabled True -Profile “Any” -Action “Allow” -Direction “Inbound” -LocalPort 9023 -Protocol “TCP”

#BIND THE INSTALLED CERT TO THE PORT TO ENABLE HTTPS - Change Cert FriendlyName and port numbers here
$thumbprint = (Get-ChildItem -Path Cert:\LocalMachine\My | Where-Object {$_.FriendlyName -match “LinxTestCert”}).Thumbprint
netsh http delete sslcert ipport=0.0.0.0:9023
netsh http add sslcert ipport=0.0.0.0:9023 certhash=$thumbprint appid=’{00000000-0000-0000-0000-000000000000}’

Run Powershell, and run the script:

./BindPort.ps1

Restart your Linx Server service

Change Linx Application Server Port number:

To change the port number of your Linx Application Server, find the “Twenty57.Linx.Server.Core.exe.config" file, usually at:“C:\Program Files (x86)\Twenty57 Linx Application Server 5\Bin\Server\Twenty57.Linx.Server.Core.exe.config”

Find the port number under appSettings tag.

Change the port number to your desired port, i.e.

<appSettings>

<add key="WebServerPort" value="9023" />

</appSettings>

Bind your SSL certificate to the new port number using steps described in the previous section.

Restart Linx Application Server service.

Rest Web Services

  • Firstly, when creating Rest Web Services, you provide a “Base URI”. Make sure that the URI is https. This will then look for a secured connection. Also, remember the port number you want to use.
  • Bind your SSL certificate to the new port as described above.
  • Deploy your solution and it should now be available over secured SSL.

SOAP Web Services

  • As with REST, you need to make sure the address provided is an https address and the correct port
  • Bind your SSL Certificate to the new port
  • Deploy your solution and test

For any additional issues please visit the community site, if you still have an unlisted issue please contact support at support@linx.software.