Skip to main content

Installation en tant que serveur Web pour Linux

Ce guide explique comment exécuter CODESYS 4 en tant que serveur sous Linux.

Compatibilité

CODESYS 4 Pour l'instant, ce paquet Linux n'est officiellement pris en charge que pour Debian. Il est possible de le rendre compatible avec d'autres distributions basées sur Debian, comme Ubuntu ou Kubuntu, mais la prise en charge sera limitée.

Remarques préliminaires

. Le fonctionnement productif de CODESYS 4 Le rôle de serveur requiert une connaissance pratique dans les domaines suivants :
  • Principes fondamentaux de l'administration système Linux

  • Gestion des utilisateurs sous Linux (PAM, LDAP, IPA, etc.)

  • Gestion des paquets sur Debian

  • Connaissance de la gestion des certificats TLS et, si possible, de l'infrastructure associée.

  • Connaissance possible de Docker, nginx et autres technologies serveur

HTTPS/TLS

CODESYS 4 utilise des API de navigateur qui ne sont disponibles que dans un contexte sécurisé. C'est toujours le cas lorsque l'accès se fait via localhost.

Dès que vous voulez faire CODESYS 4 En tant que serveur accessible aux autres ordinateurs du réseau, il est absolument nécessaire que la communication s'effectue via HTTPS, sans quoi l'application ne fonctionnera pas correctement.

Parce que CODESYS 4 Ce service ne prend pas encore en charge la communication via HTTPS ; vous devrez configurer un proxy en amont. Pour plus d'informations, consultez la section correspondante. Mise en place d'un proxy inverse TLS en amont soigneusement.

Environnement d'exécution et passerelle

Les paquets Linux de CODESYS 4 n'incluent pas actuellement un CODESYS Passerelle ou une CODESYS Durée d'exécution.

Vous trouverez les téléchargements correspondants dans le CODESYS Store.

Assurez-vous de configurer les paramètres de communication (passerelle) de votre projet afin de pouvoir accéder au contrôleur depuis le serveur.

Les utilisateurs qui travaillent sur le serveur ne peuvent y accéder qu'avec CODESYS Assurez-vous que le serveur dispose des passerelles et contrôleurs accessibles. Vous pouvez également configurer une passerelle locale directement sur le serveur.

Préparation : Création des comptes utilisateurs

Par défaut, la gestion des utilisateurs de CODESYS 4 Le serveur est basé sur la gestion des utilisateurs du système Debian. Tout utilisateur Linux ordinaire membre du codesys-4 Le groupe peut se connecter à CODESYS 4 Le serveur est activé par défaut. Cependant, vous pouvez également démarrer le serveur avec l'option --login-groups=first,second,third pour spécifier un ou plusieurs autres groupes qui devraient pouvoir se connecter à la place.

  1. Créez le codesys-4 groupe.

    Cela n'est nécessaire qu'une seule fois et se fait automatiquement lors de l'installation du paquet Debian.

    Spécifiez ici votre propre groupe si vous souhaitez utiliser un groupe différent.

    sudo addgroup codesys-4
  2. Créer le nouvel utilisateur User1 s'il n'existe pas déjà.

    (L'invite pour les informations de l'utilisateur telles que FullName, Room Number, etc. peuvent simplement être ignorés en les laissant vides.)

    sudo adduser User1
  3. Ajouter User1 au codesys-4 groupe. Attribuez l'utilisateur à un autre groupe si vous utilisez votre propre groupe.

    (Cela autorise cet utilisateur à se connecter au serveur.)

    sudo adduser User1 codesys-4

Vous pouvez créer autant d'utilisateurs que vous le souhaitez. Tous les utilisateurs qui peuvent se connecter à l'aide d'un mot de passe et qui sont membres du groupe codesys-4 Le groupe peut se connecter à CODESYS 4.

Fonctionnement en tant que serveur via systemd

CODESYS 4 car un serveur doit être exécuté sous un compte utilisateur système dédié.

Préparation

CODESYS 4 doit être installé sur le serveur web. Pour ce faire, installez CODESYS 4 selon le guide du chapitre Installation en tant qu'application de bureau pour Linux (jusqu'à la section « Installation d'un paquet Debian » incluse).

  1. Créez un utilisateur système dédié aux tests.

    > sudo useradd --system --create-home c4-server
  2. Dans le répertoire /etc/systemd/system/codesys-4.service, configurez le Service Unit fichier pour systemd

    [Unit]
    Description=CODESYS 4 Server
     
    [Service]
    Type=exec
    WorkingDirectory=/opt/codesys-4/
    ExecStart=/opt/codesys-4/c4-server --port 8080
    Restart=always
    # Restart service after 10 seconds if the dotnet service crashes:
    RestartSec=10
    KillSignal=SIGINT
    SyslogIdentifier=codesys-4-server
    User=c4-server
    Environment=ASPNETCORE_ENVIRONMENT=Production
    Environment=DOTNET_PRINT_TELEMETRY_MESSAGE=false
     
    [Install]
    WantedBy=multi-user.target
  3. Démarrer le service via systemd.

    $> sudo systemctl start codesys-4

    Le service sera disponible via HTTP sur localhost sur le port 8080.

Fonctionnement en tant que serveur via Docker

Image Docker non standard

CODESYS 4 n'est actuellement pas distribué sous forme d'image Docker. Par conséquent, il n'existe aucune image Docker officielle destinée à une utilisation en production. CODESYS 4.

Vous pouvez toutefois créer votre propre image Docker. Les étapes à suivre sont décrites plus loin dans cette section.

Connaissances préalables et soutien

Pour configurer correctement ce cas d'utilisation, une connaissance de base de Docker est indispensable. Aucune assistance ne sera fournie pour l'utilisation de base de Docker.

Exemple 3. Exemple de Dockerfile :
# Official ASP.NET 8.0 runtime base image
FROM mcr.microsoft.com/dotnet/aspnet:8.0
WORKDIR /opt/codesys-4

# The default port is 8080
EXPOSE 8080

# We have to be root to install the package, switch back to app after
USER root

# Install the Debian package for CODESYS 4.
# We set ACCEPT_CODESYS_EULA=true to skip the interactive prompt to accept the EULA during package installation.
# Building and executing this Dockerfile therefore means you accept the terms and condition of the CODESYS Engineering EULA!
RUN --mount=type=bind,source=output/,target=/tmp/output/ <<EOF
ACCEPT_CODESYS_EULA=true
dpkg -i /tmp/output/codesys-4*.deb
EOF

# The server should run with the unprivileged system user "app", see
# https://learn.microsoft.com/en-us/dotnet/core/compatibility/containers/8.0/app-user
# For security reasons, c4-server will refuse to start as root.
USER app:app
ENTRYPOINT ["/opt/codesys-4/c4-server"]


Pour créer l'image, vous devez d'abord télécharger le paquet Debian pour CODESYS 4 et enregistrez-le dans le output/ dans le sous-dossier où se trouve le fichier Dockerfile. Vous pouvez ensuite créer l'image comme d'habitude. docker buildx build commande.

Lors du démarrage de l'image dans un conteneur, sachez que seuls les utilisateurs présents dans le conteneur et membres de l'interface seront pris en compte. codesys-4 Le groupe peut se connecter au serveur (comparer avec le chapitre Préparation : Création des comptes utilisateurs).

Les utilisateurs doivent avoir accès aux mécanismes appropriés au sein du conteneur, par exemple PAM. Les répertoires personnels doivent, dans la mesure du possible, être montés comme volumes persistants dans le conteneur. Les définitions de groupes déviantes via le --login-groups Cette option peut être spécifiée dans le Dockerfile comme argument de la définition ENTRYPOINT ou être passée comme argument lors du démarrage du conteneur.

À des fins de test, vous pouvez synchroniser les utilisateurs existants sur l'hôte dans le conteneur immédiatement après son démarrage, comme indiqué dans le docker-test-example.sh scénario:

(Bien sûr, vous devrez adapter le script à vos conditions spécifiques, telles que vos identifiants de balise et votre propre registre Docker.)

Exemple 4. docker-test-example.sh (à des fins de test uniquement !)
# This script is used to start our CODESYS 4 docker containers in our
# development and test environments (RasPi, WSL, Linux VM).
# It's not regarded as safe for production use!

# The name of our container
CONTAINER=codesys-4

# The repository to fetch the image from
URL="dockerhost.example.com:1234/codesys-images/codesys-4:develop"

# Stop and clean up any running container.
if docker inspect "$CONTAINER" > /dev/null 2>&1; then
  echo Trying to clean up
  docker stop "$CONTAINER"
  docker rm "$CONTAINER"
fi

# stop and rm may fail when the container does not exist,
# but from here on, we want to abort on first error
set -e

echo Downloading "$URL"...

docker pull "$URL"

echo starting image...

# Starting the docker image.
# We mount the /home folder. We listen on port 8080.
# The option "--add-host host.docker.internal:host-gateway" allows us to access
# a CODESYS gateway running on the host machine via the hostname
# "host.docker.internal" from within the container.

docker run --restart=unless-stopped --detach \
        --volume /home:/home \
        -p127.0.0.1:8080:8080 \
        -e CBE_PORT=8080 \
        --add-host host.docker.internal:host-gateway \
        --name "$CONTAINER" \
        "$URL"

# output the version and build info, with some newlines, so it's easier readable.
echo -e \\n CODESYS 4 image build info: $(docker exec codesys-4 cat /opt/codesys-4/dist/version.json) \\n

# Ensure we have a home directory the app user can use, to write the C4 log files.
# The base image already contains /home/app, but it's shadowed by mounting our
# /home into the container, so we need to create the folder if it doesn't exist.
# Strictly speaking, this is only necessary once on a given host (because /home
# has been mounted from the host), but if we run it always, we can be sure that
# this script will also work on fresh machines.
docker exec --user 0 "$CONTAINER" bash -c "mkdir -v -p /home/app ; chown -v app:app /home/app ; chmod -v og-rwx /home/app"

# Synchronize the actual users into the container. We use a very hackish approach
# here, not recommended for production use, it just works for the dev environment.
# WARNING: Synchronizing will only work when:
# 1) The users do not yet exist within the container
# 2) The numeric user and group IDs are not yet occupied within the container.
# Also, it's recommended to configure sudo so it caches the password using
# timestamp-timeout, or even NOPASSWD if you want to take the risk.
# Only the groups codesys-4 and the user personal group will be synchronized.

echo synchronizing group codesys-4
getent group codesys-4| docker exec --user 0 -i "$CONTAINER" /bin/sh -c "cat >>/etc/group"
sudo getent gshadow codesys-4| docker exec --user 0 -i "$CONTAINER" /bin/sh -c "cat >>/etc/gshadow"

# get all users in group codesys-4
C4_USERS=$(getent group codesys-4| awk -F':' '{print $4}' | tr ',' ' ')

for CURRENT in $C4_USERS ; do
  echo synchronizing user $CURRENT

  getent passwd $CURRENT | docker exec --user 0 -i "$CONTAINER" /bin/sh -c "cat >>/etc/passwd"
  sudo getent shadow $CURRENT | docker exec --user 0 -i "$CONTAINER" /bin/sh -c "cat >>/etc/shadow"

  # we also need to synchronize the user specific group
  getent group $CURRENT | docker exec --user 0 -i "$CONTAINER" /bin/sh -c "cat >>/etc/group"
  sudo getent gshadow $CURRENT | docker exec --user 0 -i "$CONTAINER" /bin/sh -c "cat >>/etc/gshadow"
done

echo finished.


Prépositionnement d'un proxy inverse TLS

CODESYS 4 utilise des API de navigateur qui ne sont disponibles que dans un contexte sécurisé. C'est toujours le cas lorsque l'accès se fait via localhost. Dès que CODESYS 4 Étant donné qu'un serveur est accessible par d'autres ordinateurs du réseau, un chiffrement TLS, dont le certificat du serveur est approuvé par les navigateurs utilisés, doit nécessairement être mis en place.

CODESYS 4 n'implémente pas encore le chiffrement TLS. CODESYS 4 S'exécutant derrière un proxy de portail, il peut maintenir le chiffrement TLS. Sinon, un proxy inverse tel que nginx peut facilement être prépositionné à l'avance, ce qui maintiendra le chiffrement TLS. En particulier, le proxy_set_header et proxy_cache_bypass Les directives sont nécessaires pour que tout fonctionne correctement (y compris WebSocket).

Certificats SSL

Pour ce cas d'utilisation, vous avez absolument besoin soit d'un certificat SSL valide, soit d'un certificat SSL auto-signé considéré comme fiable au sein de votre organisation.

Consultez votre administrateur informatique et ne tentez pas de classer vos propres certificats comme étant de confiance sans connaissances préalables.

Si vous souhaitez toujours délivrer des certificats à des fins de test et que vous savez ce que vous faites, vous pouvez suivre le guide de la section Utilisation de certificats TLS à des fins de test Ces certificats ne doivent jamais être utilisés en production.

Nginx comme proxy inverse

L'exemple suivant illustre une configuration de nginx en tant que proxy inverse afin de maintenir le chiffrement TLS pour CODESYS 4 Vous pouvez enregistrer le fichier suivant à l'emplacement suivant : /etc/nginx/sites-available/codesys-4 Vous devez également adapter les chemins sous ssl_certificate et ssl_certificate_key aux emplacements réels de vos certificats. Ensuite, vous pouvez utiliser symlink pour activer la configuration sous /etc/nginx/sites-enabled/ et redémarrez nginx.

Exemple 5. /etc/nginx/sites-available/codesys-4
# See https://docs.microsoft.com/en-us/troubleshoot/developer/webapps/aspnetcore/practice-troubleshoot-linux/2-2-install-nginx-configure-it-reverse-proxy
# for more information.

server {
    listen	443 ssl;
    listen	[::]:443 ssl;
    ssl_certificate /etc/ssl/certs/codesys-4-certificate.crt;
    ssl_certificate_key /etc/ssl/private/codesys-4.key;

    #server_name _;
    server_tokens off; # see https://nginx.org/en/docs/http/ngx_http_core_module.html#server_tokens

    location / {
        rewrite            ^/$ /index.html last;
        proxy_pass         http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header   Upgrade $http_upgrade;
        proxy_set_header   Connection keep-alive;
        proxy_set_header   Connection "Upgrade";
        proxy_set_header   Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Proto $scheme;

        #hsts header
        add_header Strict-Transport-Security "max-age=31536000" always;
    }
}

# Redirect unencrypted http access to encrypted https access.
server {
    listen 80 default_server;
    listen [::]:80 default_server ipv6only=on;

    server_name _;

    return 301 https://$host$request_uri;
}


Certificats TLS à des fins de test

Avis de sécurité

AVERTISSEMENT : L’émission et la validation de vos propres certificats peuvent présenter un risque de sécurité important. N’effectuez les étapes suivantes que si vous disposez de l’autorisation de votre administrateur informatique. Ne tentez pas de contourner les stratégies de groupe existantes ni d’autres mesures de sécurité pour réaliser ces étapes.

Pour une utilisation optimale, il est fortement recommandé d'utiliser des certificats provenant d'une autorité de certification (AC) officielle reconnue par les navigateurs, ou à défaut, des certificats reconnus au sein de votre infrastructure d'entreprise. En cas de doute, consultez votre service informatique.

Veillez absolument à sauvegarder les fichiers de clé privée example.key et en particulier exampleca.key Ces fichiers doivent être sécurisés et inaccessibles à toute autre personne. Quiconque y accède peut les utiliser pour falsifier un nombre illimité de certificats et ainsi lancer une attaque de type « homme du milieu » contre vous ou votre organisation.

Vous pouvez utiliser le openssl La commande permettant de générer des certificats à des fins de test est indiquée ci-dessous. Auparavant, dans le example_cert.ext Dans le fichier, vous devrez modifier les noms d'hôtes pour lesquels le certificat doit être valide. Vous devrez également adapter le --subj Les paramètres des commandes doivent être adaptés à votre cas d'utilisation spécifique.

Exemple 6. exemple_cert.ext
authorityKeyIdentifier=keyid,issuer
basicConstraints=CA:FALSE
keyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment
extendedKeyUsage=serverAuth
subjectAltName = @alt_names

[alt_names]
DNS.1=localhost # adjust these to your needs
DNS.2=first.host.example.com
DNS.3=other.host.example.com


Exemple 7. Générer un certificat
# Generate development/testing certificates for CODESYS 4.

# Add the hostnames to example_cert.ext with your favourite text editor.

# Creating the CA:

openssl genrsa -out exampleca.key 2048
openssl req -new -x509 -days 365 -key exampleca.key -subj "/C=ZZ/ST=Example Kingdom/L=Example City/O=Example Organization/CN=Example Test CA" -out exampleca.crt

# Creating the Certificate:
openssl genrsa -out example.key 2048
openssl req -new -nodes -out example.csr -key example.key -subj "/C=ZZ/ST=Example Kingdom/L=Example City/O=Example Organization/CN=Example Test Server"
openssl x509 -req -days 365 -in example.csr -CA exampleca.crt -CAkey exampleca.key -out codesys-4-development-certificate.crt -extfile example_cert.ext -CAcreateserial


Important

Compatibilité

Avec un shell basé sur Cygwin – par exemple Git bash – le openssl req La commande peut échouer. Il s'agit d'un problème connu d'OpenSSL lié à Cygwin. Pour plus d'informations, consultez : https://github.com/openssl/openssl/issues/8795.

Ce problème ne devrait pas se produire lorsque vous exécutez OpenSSL dans un véritable shell Linux (également appelé WSL) ou via la ligne de commande de CMD ou PowerShell.

Le certificat racine exampleca.crt Il faut ensuite l'enregistrer comme autorité de confiance dans les navigateurs concernés. Le certificat proprement dit codesys-4-development-certificate.crt et la clé privée correspondante example.key Il doit être installé sur le serveur et référencé dans sa configuration. Par exemple, nginx peut être utilisé à cette fin (voir la section correspondante). Prépositionnement d'un proxy inverse TLS.

N'oubliez pas de retirer le exampleca.crt Certificat figurant dans la liste de vos certificats de confiance dans vos navigateurs après la phase de test.