Porteus Kiosk frequently asked questions and queries


1 ) How do I check the software version the kiosk is currently using?

2 ) Does Porteus Kiosk support customizations that are not included in the Kiosk Wizard?

3 ) How do I change the kiosk parameters that I configured in the wizard during installation? Is there any file that can be edited if I connect via SSH?

4 ) How can I install the Porteus Kiosk on my usb drive formatted with a FAT or NTFS filesystem?

5 ) How can I login to text mode to check if my customizations are working?

6 ) I would like to monitor my kiosk system while the GUI/browser is running. How can i do this?

7 ) My PC has a low amount of RAM: under 512MB. Can I still use Porteus Kiosk on this hardware?

8 ) Is it possible to use Chromium or Opera browsers in kiosk?

9 ) What's the best place to put my custom commands or start applications other than the browser?

10 ) What is default root or guest password?

11 ) After burning the kiosk on usb stick the Windows operating system shows only XX MB as available size. How can i recover my usb key?

12 ) How to troubleshoot wifi connection failures?

13 ) How can i find the PC ID which is assigned to my kiosk?

14 ) How to add missing printer driver to kiosk?

15 ) How to setup custom printer setting for the Firefox browser?

16 ) How can i use wired connection as a fallback to the wireless one?

17 ) During installation my kiosk is having troubles downloading additional components from porteus-kiosk.org website. How to workaround this problem?

18 ) Users need to provide username and password in order to access my website. How to tell the browser to remember login credentials across system reboots?

19 ) How can I host offline webpage in kiosk?

20 ) Where can I get additional help?

1 ) How do I check the software version the kiosk is currently using?

Type 'about:' or 'about:plugins' in the Firefox URL bar then press enter to check Firefox and NPAPI plugins (Flash, Java, Citrix) version respectively. If you selected Google Chrome in the wizard then please type 'chrome:version'. In order to check other components like linux kernel or Xorg you could do it by logging in the kiosk through ssh or by enabling debug mode.

System version could be checked by entering '/etc/version' in the browser URL bar or by running the 'cat /etc/version' command through ssh. File protocol support and ssh service must be activated for these methods to work.


2 ) Does Porteus Kiosk support customizations that are not included in the Kiosk Wizard?

The kiosk can be customized by placing additional modules in the /xzm folder of the unpacked ISO. See this article for more information on this subject.


3 ) How do I change the kiosk parameters that I configured in the wizard during installation? Is there any file that can be edited if I connect via SSH?

The kiosk settings are encrypted and embedded in the read-only ISO. You have to perform a full reinstallation in case you need to update even a single system parameter. If you plan to update the kiosk settings periodically then please consider enabling the remote management feature in the wizard.


4 ) How can I install the Porteus Kiosk on my usb drive formatted with a FAT or NTFS filesystem?

This is not possible. For security reasons, the kiosk ISO is burnt onto the target device in the same way that it would be burnt on a CD or DVD disc. The main reason for this is to prevent any persistent changes to the system made by malicious software or potential attackers. A kiosk reboot will always bring factory defaults except for customizations performed manually as described in the FAQ#2 above.


5 ) How can I login to text mode to check if my customizations are working?

You need to enable the ssh component and set a root password in the wizard or manually edit the /etc/shadow file from the 003-settings.xzm module and inject your password directly to it. You have to also edit /etc/inittab from the same module, change the default runlevel from '4' to '3' and uncomment at least one virtual terminal to be able to login:

    c1::respawn:/sbin/agetty 38400 tty1 linux

Once this is done please build a new module containing your custom /etc/inittab and /etc/shadow files then create new ISO with your additional xzm included. Please follow our kiosk customization guide when in trouble.


6 ) I would like to monitor my kiosk system while the GUI/browser is running. How can i do this?

For security reasons the terminal shell is disabled in the graphical mode. This means that popular applications like xterm, konsole, lxterminal or any other shell emulator will not work in the GUI. The only way of getting access to the terminal while Xorg is running is to re-enable VT switching by commenting out:

    Option "DontVTSwitch"

in the /etc/X11/xorg.conf.d/10-xorg.conf file from 003-settings.xzm. Now after booting you can press Ctrl+Alt+F1 and login to the shell as normal (make sure you complete the steps from FAQ#5).


7 ) My PC has a low amount of RAM: under 512MB. Can I still use Porteus Kiosk on this hardware?

Yes, but bear in mind that browsers are memory hungry, so you may have to enable the 'zRam' feature which will create a compressed virtual swap partition from up to 50% of your available RAM. You can enable the zRam feature through the Kiosk Wizard utility and set percentage of available RAM to be used as swap. Note that the kiosk's kernel also supports normal swap partitions on writable media (different than booting device which is always read only). If security is not a top priority - e.g. installation on an internal network - then support for swap partitions can be also activated through the wizard.


8 ) Is it possible to use Chromium or Opera browsers in kiosk?

This should be possible but requires additional effort. The kiosk includes only the libraries needed for Firefox and Google Chrome, so any additional software required for other browsers would have to be added manually. Once you resolve missing libraries and lock down the other browser to your liking, please unpack the 003-settings.xzm module and edit the /opt/porteus-scripts/gui-app file to make sure your browser restarts after being closed. You may also use our commercial custom kiosk builds service and we will do this customization for you.


9 ) What's the best place to put my custom commands or start applications other than the browser?

Our systems respect local scripts placed in the /etc/rc.d/local_(cli/gui/net).d folders so you can put your commands there. Please unsquash 003-settings.xzm and check for examples. If you want to perform some action or run a program in the GUI (Graphical User Interface) then please use the run_command parameter or edit the /opt/porteus-scripts/gui-app file from 003-settings.xzm as described in the FAQ above.


10 ) What is default root or guest password?

Root password is extremely strong, randomly generated, and unknown to anyone, including the creators of the kiosk. There is no need to change it without a reason. The guest account is locked so there is no possibility to login with guest privileges at all (the only way to use guest account is to run 'su guest' command from the root account). The only way of setting the root password in the system is to use the Kiosk Wizard and enable either SSH or printig service during the installation.


11 ) After burning the kiosk on usb stick the Windows operating system shows only XX MB as available size. How can i recover my usb key?

Kiosk uses hybrid ISO images which installs isolinux bootloader to the Master Boot Record of the drive. Its enough to delete MBR content and partition table to make the drive fully usable again. Windows users should follow this guide. Linux users can use 'dd' command to wipe the MBR of the usb stick:

    dd if=/dev/zero of=/dev/sdX bs=1M count=10

where 'X' is your pendrive letter. Be carefull to not run this command against any other drive!


12 ) How to troubleshoot wifi connection failures?

Please follow instructions below:

a) select automatic network configuration (dhcp) in the wizard and setup your wifi connection

b) when the kiosk tries to connect to the network then plug wired cable and it should connect using wired connection instead of wireless

c) enable debug mode in the wizard, skip other options and install the system

d) keep wired cable plugged, reboot PC and send generated system report to support@porteus-kiosk.org

When sending the report please give us brief description of the problem in your email.


13 ) How can i find the PC ID which is assigned to my kiosk?

The PC ID is needed in case when you want to activate automatic updates service or when you want to use nested configurations for remote management. The identification number is displayed in the Kiosk Wizard during installation, its also saved in the /etc/version file so you may access it through the browser (enter file:///etc/version in the URL bar, support for the file protocol must be activated) or ssh. When remote mangement is enabled then the kiosk config is downloaded with PC ID appended to the GET request so you can find it in the log of the server which is hosting the config. PC ID is also displayed in the Administration Panel of the Porteus Kiosk Server.


14 ) How to add missing printer driver to kiosk?

Porteus Kiosk supports over 5 thousnd printer models but some drivers may be still missing. In order to add a printer driver to the system you must remaster installation ISO manually as per this document. General procedure is as follows:

a) Download driver from printer's manufacturer website.

b) Compile the driver if necessary using recently updated Linux distribution. Follow the README file with detailed instructions if its provided with the driver archive.

c) Integrate PPD file and all extra utilities (libraries, CUPS filters, etc) with your custom module preserving correct system paths. PPD file could be saved as custom_module.xzm/usr/share/cups/model/manufacturer/driver.ppd, cups filter in custom_module.xzm/usr/libexec/cups/filter/filter_name and so on.

d) Find the driver name for each PPD. Usually it's one of the following properties in the PPD: "*ModelName" "*ShortNickName:" "*NickName:".

e) Add the driver name to custom_module.xzm/opt/scripts/files/wizard/printers.d/manufacturer-name. Take a look on existing files from 003-settings.xzm/opt/scripts/files/wizard/printers.d folder.

f) Squash your custom module and create new installation ISO with your custom module integrated. Boot the image and your recently added printer driver should be listed in the wizard.

If printing does not work then login to kiosk through ssh and run following command:

    lpinfo --make-and-model "printer_model" -m | cut -d" " -f1 | head -n1

where "printer_model" is the name of your driver. If you dont get any output from the lpinfo command then the driver name must be incorrect. If you get the driver name but printing still does not work then extra utilities may be missing or a proprietary printing service must be started. Please refer to the README file provided by the manufacturer and follow it carefully.


In case of trouble we recommend our customized builds service for creating a custom kiosk ISO with the printer driver integrated.


15 ) How to setup custom printer setting for the Firefox browser?

Printing drivers are different and its not possible to cover all configurations in the first run wizard. Luckily browser_preferences parameter allows to predefine printing settings for the Firefox browser (provided solution wont work for Chrome). Please follow setup procedure below:

a) Install testing kiosk, configure persistence for the session and enable SSH access to the system

b) Boot the kiosk and setup printing settings to your preferred values

c) Restart browser and make sure your printing settings are remembered. If this is not the case then manual modification to the PPD driver will be necessary - please contact support@porteus-kiosk.org for help.

d) Login to kiosk through ssh and run following command:

    grep print $profile/prefs.js

You should get the output as below:

    user_pref("print.print_bgcolor", false);

    user_pref("print.print_bgimages", false);

    user_pref("print.print_colorspace", "default");

    user_pref("print.print_downloadfonts", false);

    user_pref("print.print_evenpages", true);

    .... more preferences here ....

    user_pref("print.print_unwriteable_margin_left", 6);

    user_pref("print.print_unwriteable_margin_right", 4);

    user_pref("print.print_unwriteable_margin_top", 21);

    user_pref("print_printer", "kiosk-printer");


e) Copy all listed preferences and save them in some file hosted on the network

f) Reinstall the kiosk for use in a production, ativate 'browser_preferences=' parameter and point it to your Firefox preferences file

From now on your custom printing preferences will be forced in your kiosk.


16 ) How can i use wired connection as a fallback to the wireless one?

Wired and wifi connections works as a fallback to each other if you select 'Automatic IP configuration' in the wizard and setup wifi connection. DHCP performs auto configuration on all available interfaces so if one connction goes down then other can take over its role. Static IP cant be used for this purpose.


17 ) During installation my kiosk is having troubles downloading additional components from porteus-kiosk.org website. How to workaround this problem?

You could remaster installation ISO and include all modules you'll be using in the ISO by default. This way nothing would be downloaded from our server except for the wizard (true offline installations are not supported). Please follow instructions from here, standalone components can be found under this link.


18 ) Users need to provide username and password in order to access my website. How to tell the browser to remember login credentials across system reboots?

You need to set persistence to "full", disable privete mode and enable login manager. Please add following parameters to your kiosk config:

    persistence=full

    disable_private_mode=yes

    password_manager=yes


If you need to remember just one login/cookie and not the browsing history or filled forms then customized build will be necessary.


19 ) How can I host offline webpage in kiosk?

1) If your kiosk wont have an access to the network after deployment then you need to remaster installation ISO and create separate module containing your website files. System partition is limited to 900 MB by default and all data are copied to RAM during boot so this method wont work for large content with many video/image/etc files.


2) If your kiosk will have an access to LAN or internet then you can create persistent partition and upload your website files on it:

a) enable SSH access to kiosk and configure it with following parameter:

    run_command=sh /opt/scripts/persistence

This parameter will create persistent partition (900 MB is reserved for the system, remaining storage will be used for persistent partition) and automatically mount it under /opt/storage folder during kiosk boot.

b) setup browser homepage as e.g.:

    homepage=file:///opt/storage/www/index.html

c) once kiosk is up and running you can copy your website files to /opt/storage folder using for example WinSCP application and restart the kioks to make sure everything is working.


If your website requires web server to run then its necessary to add LAMP stack to it - we recomment our customized builds service for this task.


20 ) Where can I get additional help?

Please have a look on our support page.