Installatie van de MercatorPenguinServer

0000002758     -      18-12-2023

MercatorPenguinServer is een RESTfull API webservice die toelaat om gegevens uit te wisselen tussen een mobiele MercatorPenguin-applicatie en de database van Mercator. Het moet geïnstalleerd worden op een Windows-server waarop IIS (Internet Information Server)is geïnstalleerd. De installatie van deze server komt overeen met het opzetten van een website.

MercatorPenguinServer bestaat in twee versies, één voor het klassieke .net framework (4.8) en de andere voor het .net Core framework (7.0). Elke versie kan alleen Mercators van die versie bedienen. Beide versies kunnen naast elkaar bestaan op dezelfde IIS-server als afzonderlijke websites.

Installatie gebaseerd op het klassieke .net framework

  • Controleer op de IIS-server of de component ASP.net is geïnstalleerd.
  • Unzip de inhoud van MercatorPenguinServer.zip n een lokale map op de server (bijvoorbeeld C:\inetpub\wwwroot_penguin). Deze map mag niet van Mercator zijn.

Installatie gebaseerd op het .net Core framework

  • Controleer op de IIS-server of de component ASP.net is geïnstalleerd.
  • Installeer de ASP.NET Core Runtime en de .NET Desktop Runtime, te downloaden van deze pagina (kies in beide gevallen Windows X64)
  • Unzip de inhoud van MercatorPenguinServerCore.zip in een lokale map op de server (bijvoorbeeld C:\inetpub\wwwroot_penguincore). Deze map mag niet de Mercator map zijn.

Het is noodzakelijk dat er een up-to-date Mercator-installatie op de server aanwezig is.

In de console van IIS moet men een nieuwe website creëren.

iis_ajouter_website_NL

Als pad moet u de hierboven gebruikte map opgeven.

Ook is het noodzakelijk om de hostname te registreren in uw DNS: bijvoorbeeld penguin.domain.com

Deze nieuwe site vereist geen specifieke beveiligingsinstellingen, u moet enkel schrijfrechten toekennen aan de submap LogFiles. In deze map zal de MercatorPenguinServer de logbestanden registreren. Deze zelfde parametregin is nodig op de submap Bin om de automatische update van MercatorTunnel.dll mogelijk te maken.

Installatie gebaseerd op het klassieke .net framework

  • De bijbehorende applicatiepool moet de eigenschap .NET CLR version hebben ingesteld op v4.0.030319.

Installatie gebaseerd op het .net Core framework

  • De bijbehorende applicatiepool moet de eigenschap .NET CLR version hebben ingesteld op No Managed Code.
  • De MercatorPenguinServerCore.exe server communiceert met een instantie die specifiek is voor elke Mercator-map (PenguinServerMercatorInstance.exe) op een TCP-poort die door de server wordt gekozen uit de waarde die wordt vermeld in appsettings.json onder de parameter BaseTcpPort. De standaardwaarde is 15000, wat betekent dat TCP poorten 15000 en hoger toegankelijk moeten zijn binnen de server. (Het is echter helemaal niet nodig of niet aanbevolen om deze poorten op het netwerk te openen). Indien nodig kan de BaseTcpPort waarde worden aangepast.

Omwille van beveiligingsredenen is de MercatorPenguinServer enkel toegankelijk via HTTPS, daardoor bent u verplicht om een SSL-certificaat te installeren. Poort 443 (https) moet ook geopend worden, deze moet naar de server verwijzen. Het SSL-certificaat is gratis verkrijgbaar via LetsEncrypt.

MercatorPenguinServer kan gebruikt worden om gelijktijdige toegang te bieden tot meerdere Mercator-dossiers. Hiervoor moet de MercatorPenguinServer één of meerdere configuratiebestanden bevatten, welke geplaatst kunnen worden in de submap App_Data, waarvan de naam als volgt is samengesteld:

  • De naam van het bestand moet de naam zijn die wordt ingevuld in de MercatorPenguin-verbindinsinstellingen.
  • De extensie is altijd .ini

De structuur van de inhoud van het bestand moet identiek zijn aan de structuur van het meegeleverde: config.ini

Het moet als volgt vervolledigd worden:

  • MainDir: map met de Mercator om verbinding mee te maken. Opgelet: Deze map moet een lokale map zijn, inderdaad, een Windows-service kan externe mappen niet zien.
  • Dossier : ID van het dossier indien het om een multi-dossier gaat. Als dit niet het geval is, mag je de instelling leeg laten
  • SecretPhrase : De wachtwoordzin die gebruikt zal worden om de te verzenden berichten te versleutelen tussen MercatorPenguin en de MercatorPenguinServer. Deze zin moet ook ingegeven worden in de MercatorPenguin-verbindingsinstellingen. We raden aan om een voldoende sterke zin te gebruiken en wachtwoorden als “1234” te vermijden.
  • MaxRows : een mobiele gebruiker kan geen catalogus met 30 000 items ontvangen, waarschijnlijk zal het toestel zelfs niet in staat zijn om al deze informatie in het geheugen te bewaren. Het aantal rijen dat een dataset, die naar de gebruiker teruggestuurd wordt, bevat moet daarom worden beperkt. Dit aantal rijen kan je hier invullen, de aanbevolen waarde is 50.
  • AdDomain en AdGroup : We raden aan om de authenticatie te gebruiken die gebaseerd is op het Active Directory. Indien dit het geval is, moet dit hier vermeld worden, respectievelijk het domein (mydomain.local) en de groep waartoe de gebruiker toegang moet hebben om met Mercator te communiceren. Indien dit veld leeg is worden de gebruikers geverifieerd op basis van de in Mercator gecodeerde logingegevens. Deze laatste optie is verouderd.

 

Het bestand web.config of appsettings.json, welke zich in de hoofdmap bevindt omvat volgende parameters:

  • DaysLogs : aantal dagen om de logbestanden bij te houden. Bij het starten van de webservice worden oudere logbestanden automatisch verwijderd. Indien u het automatisch verwijderen wilt uitschakelen moet u hier nul (=0) ingeven. De standaardwaarde is 30 dagen.
  • IpBlockerNbraantal mislukte aanmeldpogingen, waarna het IP-adres van de gebruiker op de blacklist komt voor een vooraf bepaalde tijd. De standaardwaarde is 10.
  • IpBlockerMin : aantal minuten dat een IP-adres geblokkeerd is, standaardwaarde is 15 minuten.
  • JpegCompression : Compressie-instelling voor afbeeldingen die weergegeven worden door ShowImage.ashx. De standaardwaarde is 50.

Waarom is de beveiliging die MercatorPenguinServer biedt betrouwbaar?

  • De gegevensuitwisseling verloopt via het HTTPS-protocol. Dit verzekert een beveiligde verbinding, en maakt het onmogelijk om gegevens in het overzicht te onderscheppen.
  • Niet elke aanvraag wordt geaccepteerd door MercatorPenguinServer, dit wordt alleen geaccepteerd indien er specifieke HTTP-headers aanwezig zijn.
  • Deze headers omvatten het uitwisselen van een hash-sleutel en een token voor eenmalig gebruik, om te verzekeren dat de verzender van het bericht MercatorPenguin is.
  • De token maakt deel uit van dit hashing-scenario, evenals de geheime wachtwoordzin, welke uniek is voor elke configuratie en onbekend is voor MercatorPenguin en de MercatorPenguinServer.
  • MercatorPenguinServer omvat het systeem om IP-adressen tijdelijk te blokkeren, dit gebeurt wanneer het IP-adres meerdere verzoeken verzend met onjuiste sleutels/tokens of onjuiste logingegevens doorsturen.
  • De SQL-query’s die uitgevoerd worden, worden nooit naar de MercatorPenguinServer verzonden. De MercatorPenguinServer gebruikt steeds de originele query’s die zich in Mercator bevinden. Bovendien gebruiken alle SQL-query’s alleen SQL-parameters. Deze twee punten maken SQL-injectie onmogelijk.

 

Alleen voor .net-framework 4.8

Als men de foutmelding HttpStatusCode=NotFound te zien krijgt in de mobiele toepassing (en alleen in dit geval), moet men deze lijnen toevoegen in het web.config bestand, vóór </system.webServer>

<handlers>
    <add name="ApiURIs-ISAPI-Integrated-4.0"
         path="/api/*"
         verb="GET,HEAD,POST,DEBUG,PUT,DELETE,PATCH,OPTIONS"
         type="System.Web.Handlers.TransferRequestHandler"
         preCondition="integratedMode,runtimeVersionv4.0" />
</handlers>

 

Als de fout HttpStatusCode=Forbidden wordt aangetroffen in de mobiele applicatie (met "Security headers error 3" in het logbestand), moet de wachtwoordzin worden gecontroleerd.
Deze is inderdaad hoofdlettergevoelig.

Versies

  • 12/12/2017 : v 1.0.1 : multi-threading verbetering in het wegschrijven van logbestanden.
  • 29/05/2018 : v 2.0.0 : compatibel met MercatorPenguin 2.0
  • 28/06/2018 : v 2.1.0 : compatibel met MercatorPenguin 2.1
  • 18/09/2018 : v 2.2.0 : compatibel met MercatorPenguin 2.2
  • 03/10/2018 : v 2.2.1 : compatibel met MercatorPenguin 2.2.1
  • 13/10/2018 : v 2.2.1.1 : bug fixing berekening ItemsSource van EditPickers
  • 20/10/2018 : v 2.2.1.2 : bug fixing creatie nieuwe fiche in informatiebestand zonder standaard data + compatibiliteit Roslyn-compilatie van rapporten
  • 23/10/2018 : v 2.2.1.3 : rekening houden van het PenguinServerBeforeValidateData-evenement van de MercatorUi.Sig.Sig class  Update van alle Mercators noodzakelijk!
  • 22/11/2018 : v 2.2.1.4 : rekening houden van het PenguinServerBeforeValidateData-evenement van de BillingEngine en de ActionEngine  Update van alle Mercators noodzakelijk!
  • 22/11/2018 : v 2.2.1.5 : initialisation différée d'instance de MercatorUi.Main en cas d'erreur au démarrage, soit via la page de maintenance, soit à la prochaine sollicitation de cette instance + dans la page de maintenance, prise en compte des modifications apportées dans les fichiers ini.
  • 07/12/2018 : v 2.2.1 : compatibel met MercatorPenguin 2.2.2
  • 09/12/2018 : v 2.2.2.1 : automatische update van assembly's en SQL-bestanden die moeten worden gedistribueerd voordat de instance wordt gestart
  • 11/12/2018 : v 2.2.2.2 : correctie SQL-fout tijdens informatiebestand bewaren, i.v.m. @current_modiftag
  • 31/01/2019 : v 2.3.0 : compatibel met MercatorPenguin 2.3 (SumUp)
  • 19/02/2019 : v 2.4.0 : compatibel met MercatorPenguin 2.4 (signatures)
  • 16/03/2019 : v 2.4.0.1 : ReqSql in SearchPickers
  • 02/05/2019 : v 2.5.0 : RunDocumReport : rekening houden met de gebruiker 
  • 09/05/2019 : v 2.5.1 : compatibel met MercatorPenguin 2.5 (virtual scan)
  • 11/05/2019 : v 2.5.2 : bug fix onder iOS "Default constructor not found for type System.Array"
  • 25/10/2019 : v 2.6.0 : compatibel met MercatorPenguin 2.6.0   Update van alle Mercators noodzakelijk!
  • 04/11/2019 : v 2.6.1 : notificaties verzenden:gebruikers uitsluiten die niet in penguin_players zijn opgenomen
  • 10/01/2020 : v 2.6.2 : parameter MaxRows in de SQL query bepalen
  • 11/01/2020 : v 2.7.0 : compatibel met MercatorPenguin 2.7
  • 22/06/2020 : v 2.8.0.10 : compatibel met MercatorPenguin 2.8  Update van alle Mercators noodzakelijk!
  • 28/06/2020 : v 2.8.0.11 : bug fixing billing licensing
  • 01/07/2020 : v 2.8.0.12 : bug fixing Maintenance.aspx
  • 09/07/2020 : v 2.8.0.13 : bug fixing billing licensing : als LOT of MPLACE opties ontbreken
  • 19/08/2020 : v 2.8.0.14 : bug fixing Maintenance.aspx (disabling device)
  • 21/09/2020 : v 2.9.0 : compatibel met MercatorPenguin 2.9  Update van alle Mercators noodzakelijk!
  • 07/10/2020 : v 2.9.1 : artikel zoeken: optimalisatie via opties N_BARCODE en RECH_S_ID
  • 25/11/2020 : v 2.9.3 : compatibel met MercatorPenguin 2.9.3  Update van alle Mercators noodzakelijk!
  • 09/12/2020 : v 2.9.4 : compatibel met MercatorPenguin 2.9.4
  • 13/01/2021 : v 2.9.5.0 : compatibel met MercatorPenguin 2.9.5  Update van alle Mercators noodzakelijk!
  • 18/01/2021 : v 2.9.5.1 : bug fix inventarissen & transferts tussen depôts
  • 19/03/2021 : v 2.9.5.2 : compatibel met MercatorPenguin 2.9.6
  • 07/04/2021 : v 2.9.7.0 : compatibel met MercatorPenguin 2.9.7
  • 06/07/2021: v 2.9.7.1 : correctie van het tellen van devices (geen rekening houden met de gebruiker)
  • 09/09/2021 : v 2.9.8.0 : compatibel met MercatorPenguin 2.9.8  Update van alle Mercators noodzakelijk!
  • 26/10/2021 : v 2.9.9.0 : compatibel met Mercator 10.10
  • 22/11/2021 : v 2.9.10.0 : compatibel met MercatorPenguin 2.9.9  Update van alle Mercators noodzakelijk!
  • 07/12/2021 : v 2.9.11.0 : compatibel met MercatorPenguin 2.9.11  Update van alle Mercators noodzakelijk!
  • 02/02/2022 : v 2.10.0.0 : compatibel met Mercator MercatorPenguin 2.10.0  Update van alle Mercators noodzakelijk!
  • 21/03/2022 : v 2.10.0.1 : altijd InitReporting uitvoeren bij instantie-initialisatie
  • 06/04/2022 : v 2.10.0.2 : rekening houden met event BillingEngine.PenguinServerHandlingReqSql2  Update van alle Mercators noodzakelijk!
  • 17/05/2022 : v 2.10.0.3 : corr. artikel beschikbaarheid op locatie, indien buiten locatie
  • 22/06/2022 : v 2.10.6 : compatibel met MercatorPenguin 2.10.6  Update van alle Mercators noodzakelijk!
  • 29/06/2022 : v 2.10.7 : corr. compatibiliteit lots en inventarissen
  • 22/07/2022 : v 2.10.9 : compatibel met MercatorPenguin 2.10.9 +SQL SSL certificaten  Update van alle Mercators noodzakelijk!
  • 18/10/2022 : v 2.10.13 : compatibel met MercatorPenguin MercatorPenguin 2.10.13
  • 01/12/2022 : v 2.10.15 : corr. upload SQL-bestanden in acties
  • 04/12/2022 : v 2.10.16 : compatibel met MercatorPenguin 2.10.16 : warning in TargetSig
  • 13/12/2022 : v 2.10.17 : IXmlDocumentUpdaterWithContextInfo kan ook werken op XamlListViewCellin wijzigbare documenten
  • 17/12/2022: v 2.10.18 : C_IDCOMPTA en F_IDCOMPTA van nieuwe klanten/leveranciers invullen
  • 20/12/2022 : v 2.10.19 : corr. mogelijk fout "Value cannot be null" in RunSql
  • 01/05/2023 : v 2.10.20 : compatibel met Mercator 11.0
  • 15/05/2023 : v 2.10.21 : vervanging van System.Windows.Forms.DataVisualization.Charting (zie deze pagina)
  • 21/07/2023 : v 2.10.22 : compatibel met MercatorPenguin 2.10.22 : geavanceerde picking
  • 12/09/2023 : v 2.10.23 : PDF duplicaten genereren
  • 20/09/2023 : v 2.10.24 : compatibel met MercatorPenguin 2.10.24 : EditActionRights  Update van alle Mercators noodzakelijk!
  • 05/12/2023: v 2.10.26: compatibiliteit met MercatorPenguin 2.10.26: gepersonaliseerde hiërarchische EditEntry + Picking: commentaar geven op de gepickt regels + rekening houden met BLOCK_SOMMEIL en BLOCK_NONDISPO  Update van alle Mercators noodzakelijk!

Ook bekijken: Procedure voor het updaten van MercatorPenguinServer

Een LetsEncrypt certificaat instellen

1) Installeer de webservice volgens de beschrijving van deze pagina. Zorg er voor dat de url http://penguin.domain.com/testprocess.ashx “OK” retourneert. Als dit het geval is, is de webservice gestart en functioneel, zoniet corrigeert u de configuratie alvorens u door gaat naar de volgende stap. Stel niets handmatig in met betrekking tot de HTTPS-verbinding.

2) Poort 80 (http) moet geopend worden, deze moet naar de server verwijzen.

3) Download de letsencrypt-win-simple applicatie via https://github.com/Lone-Coder/letsencrypt-win-simple/releases  

4) Voer letsencrypt.exe uit. . Indien dit de eerste keer is, moet je de licentie aanvaarden en een emailadres opgeven waarop u meldingen met betrekking tot het verlopen van het certificaat wilt ontvangen.

5) In de uitnodiging geeft u het nummer van de site in dat overeenkomt met pinguin.domain.com.

6) Indien het de eerste keer is dat u een certificaat aanvraagt, moet u het aanmaken van een Windows-taak bevestigen. Deze taak zal het certificaat automatisch vernieuwen om de 60 dagen.

7) Test de url https://penguin.domain.com/testprocess.ashx 

Let's Encrypt