Porteus Kiosk Server


The main purpose of the server is to allow accessing and performing management tasks on the kiosk clients even if they are placed behind a NAT, proxy or firewall.

Porteus Kiosk Server is different compared to the standard kiosk system in the following aspects:

  • Administration Panel is launched during system startup instead of the browser
  • Bottom panel is available
  • Conky applets are used for server system and server log monitoring purposes
  • Contents:

    Requirements

    Setup procedure

    Pricing

    Terms and conditions

    Remote management

    Troubleshooting connection problems

    Real time monitoring of the client resources

    Client logs

    Client files

    Server migration

    Server reconfiguration

    Requirements

    Once the server and clients are up and running a SSL tunnel is created between them to allow communication through the SSH and VNC protocols (both are embedded in the SSL tunnel).


    The following requirements must be met for the server to work:

  • Server must be installed in a network location which is accessible by the clients.
  • SSL tunneling daemon listens on port 443 on the server so incoming connections to this port must be allowed in your router/firewall configuration.
  • If PK Server is installed on the virtualization platform like VMware, Hyper-V, VirtualBox, QEMU then at least 2GB of RAM and 64MB of video memory should be allocated to the virtual machine otherwise the server may not work correctly.
  • Server must be able to access porteus-kiosk.org domain on ports 80 and 443 in order to validate the subscription and receive system updates. Please make sure your firewall is not blocking these ports on our domain.

  • The following requirements must be met on the client's side:

  • Client must be able to reach Porteus Kiosk Server on port 443 the same way it is accessing e.g. google.com website (client initializes connection to the server).
  • The kiosk clients must be installed with support for Porteus Kiosk Server enabled in the wizard. kiosk_server and client_id parameters must be present in the kiosk config.
  • SSH and VNC services must be enabled on the clients.


  • Setup procedure

  • Download Porteus Kiosk Server installation ISO from your account in the Customer Panel.

  • Boot the system and follow the wizard to setup an internet connection, choose a preferred browser and configure the server. Send the Server and Customer IDs to sales@porteus-kiosk.org in order to get the server activated for a 30 days trial if needed.
  • When the server is up and running, configure the kiosk clients with support for Porteus Kiosk Server. Make sure the kiosk_server and client_id parameters are present in the kiosk config and ssh/vnc services on the client are enabled.
  • NOTE: if you use remote management with nested configurations enabled then kiosk_server parameter should be placed in the GLOBAL section of your remote config while client_id must be placed in the PCID sections and be unique per kiosk. Sample config can be found here.

    EXCEPTION: Porteus Kiosk clients in version 4.3.0 and above can be configured with parameter 'client_id=automatic' which does not have to be unique per client and can be placed in the GLOBAL section of remote config. Sample configs for clients 4.3.0 and above can be found here and here.

  • Once all kiosk clients are booted you can update the clients list in the Administration Panel and start management or monitoring tasks.
  • Features and pricing

    Porteus Kiosk Server subscription costs €300 euros (excl. VAT) per year.


    If you are a public or educational institution, foundation or non profit organization then the server price could be lowered to a level which is affordable for you. Please query sales@porteus-kiosk.org for a quote and request an additional discount!


    NOTE: Porteus Kiosk Server cannot upgrade the client systems. Clients must update from our domain server (for security reasons we do not allow to host the system updates anywhere else) and require a separate subscription.


    The Administration Panel supports following functions:


    General features:
    Administration panel
    Number of supported clients Up to 1000
    Monitoring tasks:
    Monitor which kiosks are online
    Display client details: system/browser/kernel version, MAC/IP, hostname, other
    Monitor client resources: CPU, RAM, temperature, used bandwidth, other
    Monitor system log of the clients
    Interaction with the clients:
    Wake On Lan
    VNC connection: view-only or interactive
    SSH connection
    Mount remote filesystem locally
    Synchronize local and remote content
    Restart browser/Xorg session
    Reconnect/reboot/shutdown the client
    Update client's homepage temporarily (use remote management for persistent change)
    Send custom command to the client: e.g. display notification
    Generate detailed system log of the client
    Remote management:
    Host client configuration on the server
    Host client files on the server
    System:
    Email notifications (e.g. client went offline, high server CPU usage)
    Backup and restore server files
    Persistence for the client list, logs, config, files and custom startup scripts
    Bottom panel with application launcher, task manager, systray, etc
    VMware tools/VirtualBox guest additions
    Price (excl. VAT): €300/year



    Terms and conditions that apply to Porteus Kiosk Server subscription

    Last updated: July 11, 2024


    1) Before you buy the server subscription you are entitled for a 30 days free trial. Please install the server and contact sales@porteus-kiosk.org in order to activate the trial. If 'client -> server' communication issues occur please contact support@porteus-kiosk.org and we will assist you with resolving them.


    2) When buying the subscription you obtain the right to update your server remotely and automatically, to use the functions offered by the server's Administration Panel and to receive the support for resolving the issues which you are facing. This is the actual subject of your purchase and you have no other rights granted. Please remember that you do not become a software owner after paying for the subscription - it still belongs to the original authors.


    3) You can buy the server subscription through your account in the Customer Panel.


    We accept online payments only: wire bank transfer and credit/debit card payment. Please do not send us bank checks as our bank: ING Bank Slaski does not accept them.


    4) Balance on your account in the Customer Panel will be updated once the payment is logged on our PayPal or bank account.


    5) In order to get the server fully operational you need to activate the relevant Server ID using the Customer Panel. During the next boot the server should validate the subscription and upgrade automatically to the latest available system version.


    6) Server subscription is valid for 12 months. Renewal notice will be sent to your email address 30 days before the subscription expires. If the subscription is not extended for another year then the server stops working as we do not allow it to operate with outdated/vulnerable components. If you have a renewal date set in the Customer Panel already and want to buy an additional server subscription then you will be charged for the number of days which are left until the renewal date.


    7) If you decide to cancel the server's subscription before the renewal date then please query sales@porteus-kiosk.org and the remaining part of the money will be refunded to you within 30 days after receiving the note.


    8) You have the possibility of moving the subscription from one server to another in case of e.g. hardware failure. Please follow the migration guide in order to perform a permanent swap.


    9) Porteus Kiosk Server issues (configuration, software, hardware) will be resolved without additional charge during the whole subscription period. Standard support queries will be answered within 24 hours over the email. Urgent/critical issues affecting the server could be resolved through remote assistance within the same time frame.


    10) LIMITATION OF LIABILITY. Porteus Kiosk Server may fail to work for reasons which are independent from us: our domain/update servers became unavailable due to a VPS provider fault, upstream linux developers introduce a bug in the code which they maintain, etc. We may also make occasional mistakes ourselves. In any case the liability for direct losses on your side are limited to the amount which you paid for the subscription. If you are no longer content with the service then you should cancel it as per terms included in point 7). You cannot claim for the amount which exceeds your current payment for the service.




    Remote management

    Clients in version 4.1 can be configured to download its configuration file directly from Porteus Kiosk Server. This is useful if you want to avoid using a web hosting service. Please follow remote management document for more information about this feature.


    Kiosk configurations which are stored on a web hosting service must be saved in plain text so it's possible to edit them easily. This requirement brings security concerns as anybody who knows or finds the config URL can read the passwords and other sensitive data which are stored in it (internet bots/spiders/crawlers systematically caches and parses the webpages on the internet). These concerns are addressed by the Porteus Kiosk Server product.


    Configurations which are stored on our server are encrypted by default. They can be added, modified and deleted using the Administration Panel application only. You cannot manage the configs on the server using command line or over SSH, you need to use our dedicated application for this task. Config files are downloaded by the clients through secure SSL and SSH tunnels and should never be captured and malformed by 3rd parties.


    Setup procedure is very similar to remote management with configs stored on a web server. Changes are bolded below.


    Setup of the first kiosk should be as follows:

    a) boot Porteus Kiosk installation ISO on the target PC

    b) setup network then select 'Launch wizard to create new configuration' on the initial wizard screen

    c) enable 'Remote kiosk management' in the wizard options and provide the name of the config which will be stored on the server (this config is not present on the server yet, you will add it in the next steps). Following format is required: server://config_name

    NOTE: 'server://' part is a text string indicating connection type and cant be replaced with your server IP or domain, sample: link

    d) set other kiosk functions as you like

    e) on the final configuration window in the wizard take a copy the config and send it to your email address or save on removable media

    f) create a new config in the 'Remote Management' tab of the Administration Panel on PK Server. Preserve the name of the config which was provided in the wizard during client installation. You can copy the parameters to the server using VNC service (VNC access must be enabled during server installation) or using the browser. Open the browser on your server, login to your web email and copy parameters from your saved email to the Administration Panel. Please do not type the parameters manually to avoid mistakes.

    g) install kiosk and check if it's able to download the config from the server during first boot


    Configuration of additional kiosks:

    a) boot Porteus Kiosk on target PC

    b) setup network then select 'Point kiosk to existing remote configuration' on the initial wizard screen and provide name of the config which is stored already on Porteus Kiosk Server, example: server://group1.txt

    c) install the kiosk



    Troubleshooting connection problems

    If you experience problems with connecting clients to the server then please do as follows:


    1) Make sure that the kiosk client was configured with the following parameters enabled (sample parameter values are used below). These parameters are required to make connection to the server:

      kiosk_server=domain.com:443

      client_id=automatic

      additional_components=08-ssh.xzm 09-x11vnc.xzm (add other components like uefi.zip, fonts, printing, etc if needed)


    2) Type server address (value of the kiosk_server= parameter with 'https://' prefix added) in the browser URL bar on the client:

      https://domain.com:443

    Press enter and check if you can connect to the server. If the browser returns a 'Secure connection failed' message then everything is OK.


    Error message indicates that the browser did not have a valid certificate to be able to connect to the "stunnel" daemon and this is expected.


    If you receive an 'Unable to connect' message then it's your network or firewall configuration fault. Please remember that the client must be able to access Porteus Kiosk Server the same way it's accessing e.g. "porteus-kiosk.org" website.


    3) Press 'Refresh list' in the Administration Panel of the server to check if the client connected successfully.



    Real time monitoring of the client resources

    WARNING: large number of monitored clients may cause performance impact on Porteus Kiosk Server. In the Administration Panel you need to explicitly select clients and resources which you want to monitor. Only the first 100 (online) clients are currently allowed for monitoring - this is to ensure that PK Server can operate normally despite extra tasks added.


    If you notice that server CPU usage (visible in the conky applet) goes to 70% and above then please lower the number of clients or resources which are monitored. If your server has dedicated 4 cores of Intel i3 class CPU or higher then it should handle 100 clients without much stress - see the screenshot below.


    Client resources monitoring is implemented server side and works for all client versions including 32bit kiosk releases.

    Following data can be pulled from the clients: usage of CPU/RAM/swap/root (virtual filesystem)/storage (persistent partition), CPU temperature, downloaded/uploaded data, battery charge level, and client uptime. This feature may be useful for debugging purposes and proactive maintenance.


    Data is presented in the Administration Panel and updated every 2 seconds. It's possible to sort the client list by specific categories, e.g. highest CPU usage.


    If your project requires monitoring some other client resources then please contact us and will consider adding them to our platform.


    Porteus Kiosk Server with Intel i3 CPU handling 70 clients monitored in real time, client list is sorted by the uptime category:

    (click to enlarge)



    Client logs

    If the client is in version 4.1 or above then it will automatically send its system logs in severity warning or above to PK Server. This is useful for proactive support and gives you a chance to take action before a critical condition occurs.


    Client logs are displayed in the reverse order (newest on top) in the Administration Panel. They are stored on the server in /var/log/remote.log file which is persistent across server reboots but gets rotated once it reaches 1MB in size. Administration Panel allows to view full client log, filter client logs by specific string (e.g. client ID), display archived (rotated) logs or delete all client logs from the Server.


    If the 'Client Logs' tab in the Administration Panel remains empty then you can be almost sure that your kiosk clients work without problems.


    Please do as follows to check if logging works correctly:

    a) open SSH connection to the client

    b) generate event with following command:

      logger -p local2.warning Please help - im having troubles

    c) check if the log you just generated is recorded in 'Client logs' tab of the Administration Panel


    If you run following command on the client side:

      logger -p local2.notice Please help - im having troubles

    then your message will get into system log of the client (/var/log/messages) but will never be transported on the server as its severity level is below 'warning'.


    If client logging does not work as expected then please contact support@porteus-kiosk.org for assistance.



    Client files

    Clients in version 4.2 and above can be configured to download files directly from Porteus Kiosk Server. You need to add the files to PK Server using the Administration Panel ('Client Files' -> 'Add file') and then configure the clients using server:// string instead of traditional http(s):// or ftp://.


    Currently supported parameters are listed below:

      wallpaper=server://file.png

      browser_preferences=server://firefox_prefs.txt

      screensaver_archive=server://images.zip

      proxy_config=server://proxy.pac

      import_certificates=server://certificate1.crt


    Please mind that the video file used for the 'screensaver_video=' parameter is an exception and cant be hosted on the server.


    WARNING: Please do not upload your kiosk configs to the 'Client Files', you need to use the 'Remote Management' section for this otherwise the config won't be accessible for the clients.


    If you get into troubles with configs or files stored on Porteus Kiosk Server then please contact support@porteus-kiosk.org for assistance.



    Server migration

    Installed server is bound to the hardware, for this reason you cannot move the hard drive or clone the virtual machine when migrating the server. Your old server will refuse to boot on new hardware.


    Please complete following steps to perform the migration:

    1) generate backup on the old server using the 'Administration Panel -> Tools -> Backup server files' utility and upload it to your webmail (using the browser on PK Server) or desktop (using SSH connection with e.g. WinSCP utility)

    2) install server on a new VPS/virtual machine/PC

    3) login to your account in the Customer Panel, deactivate the old server and activate the new server (old server will still work for about 2 days after deactivation)

    4) reboot the new server and restore the backup on it using the 'Administration Panel -> Tools -> Restore server files' utility

    5) update the DNS/firewall rules in your organization to redirect the client's traffic to your new server IP address

    6) in case the public server IP is different you may need to reboot the clients so they could refresh the DNS cache and connect to a new server



    Server reconfiguration

    Porteus Kiosk Server system is read only (for safety reasons only selected folders are persistent) and its config is encrypted. If you want to change the settings which you selected in the wizard during server installation: IP address, VNC port, SSH password, etc then you need to reinstall the server.


    When reinstalling the server please keep the persistent partition unformatted (this is default option in the installation wizard) so your custom files: remote configs, client logs, client files, etc will be still available when the server is back online.


    Please also do a server backup before reinstallation: 'Administration Panel -> Tools -> Backup server files' and copy the backup to your own PC. This is to cover an emergency case when something goes wrong during the reinstallation.


    Server ID is generated from the hardware so it will not change when you reinstall the server.


    WARNING: when reconfiguring the server please do not create a new virtual machine/server instance. You need to reuse the old VM/hardware as your client files are still present on it. The Server ID must also remain the same after reconfiguration.