Porteus Kiosk

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

For the Firefox browser please enter 'about:buildconfig' in the Firefox URL bar, click on the 'Built from' link and you should find the 'milestone' number which represents the Firefox version. 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 'file:///etc/version' address in the browser's URL bar or by running the 'cat /etc/version' command over 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 the following 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 wont be able to update them over SSH. You need to perform full reinstallation in case you need to update even a single system parameter. If you plan to update the kiosk settings more often then please consider enabling the remote management feature during kiosk installation.

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 boot 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 'tty1' virtual terminal to be able to login to the system:

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+F2 and login to the system as normal (make sure you enable 'tty2' as explained in FAQ#5).

7 ) My PC has a low amount of RAM. 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 swap files which are placed on persistent partition. Support for swap files 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/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 sample scripts in these folders. 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/scripts/gui-app file from 003-settings.xzm as described in the FAQ above.

10 ) What is default password for user root and guest?

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). You may set custom root password in Kiosk Wizard by enabling 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. Please boot any live Linux and run 'dd' command as root 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 the 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 by connecting to kiosk through SSH and running 'cat /etc/version' command. When remote management 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 web server which is hosting the config. PC ID is also displayed in the Administration Panel of Porteus Kiosk Server.

14 ) How to add missing printer driver to kiosk?

Porteus Kiosk supports thousands of 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 with following functions activated in the wizard: disable private mode for the browser, configure persistence for the session, 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. It could be implemented in a customized build - please contact builds@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.printer_kiosk-printer.print_bgcolor", false);

user_pref("print.printer_kiosk-printer.print_bgimages", false);

user_pref("print.printer_kiosk-printer.print_colorspace", "default");

user_pref("print.printer_kiosk-printer.print_downloadfonts", false);

user_pref("print.printer_kiosk-printer.print_evenpages", true);

.... more preferences here ....

user_pref("print.printer_kiosk-printer.print_unwriteable_margin_left", 6);

user_pref("print.printer_kiosk-printer.print_unwriteable_margin_right", 4);

user_pref("print.printer_kiosk-printer.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, activate '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 can not 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 installers are supported only through the customized builds service). 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 private 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 only selected 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.

Please also setup static IP in the wizard (could be random values) to avoid 120 seconds delay and 'Gateway not found' warning message during kiosk boot.

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 kiosk 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 ) How to force booting the kiosk from removable media to test new system version or configuration?

In some cases it may be desired to test specific kiosk version or configuration on certain hardware prior to updating the kiosk system whihc isinstalled on the hard drive. In order to force booting the kiosk from removable media (applies to USB, SD/MMC, CD/DVD storage) you need to add following parameter to your kiosk config during system installation:

kernel_parameters=boot_from_usb

21 ) How to prevent the kiosk updating the PC's hardware clock?

If kiosk is installed on removable device and you are using it occasionally e.g. to do an online banking, then you may want to prevent the kiosk updating the hardware clock as it probably affects the system time in your main operating system. If this is the case then you need to point the kiosk to some non existing NTP server in order to never update the hardware clock. Please use this parameter in your kiosk configuration:

ntp_server=fake.server.org

22 ) How to configure multiple scheduled actions in the system?

'scheduled_actions=' parameter supports Linux shell syntax so its possible to execute commands one after another by separating them with a semicolon. If you want to restart the browser at 11:30 in the morning and stop the kiosk at 18:00 in the afternoon then you need to use following parameter:

scheduled_actions=Monday-11:30 Tuesday-11:30 Wednesday-11:30 Thursday-11:30 Friday-11:30 Saturday-11:30 Sunday-11:30 action:killall chrome; sleep 390m; halt

'sleep 390m' command tells the system to wait 390 minutes (6.5 hours) before powering off the system.

If you need to perform different actions at specific day in a month or a year then you need to utilize cron daemon for this task. You can inject cron jobs directly to the crontab using the 'run_command=' parameter:

run_command=echo '0 9 * * 1-5 root su - -c your_command' >> /etc/crontab; echo '0 10 * * SAT,SUN root su - -c your_command' >> /etc/crontab

Mind that in kiosk's crontab you need to specify the username which will execute the command.

If you have many actions to schedule then it may be easier to use 'run_command=' parameter to download and replace original /etc/crontab:

run_command=wget https://domain.com/files/kiosk/crontab -O /etc/crontab

There is no need to restart the cron as the cron daemon automatically discovers the changes made to it's config.

23 ) How can I append custom flags (command line switches) to Chrome?

Please utilize 'run_command=' parameter for this task:

run_command=grep -q "your-flag" $chflags || echo '--your-flag --your-flag2 --your-flag3' >> $chflags

Example for 'disable smooth scrolling' function:

run_command=grep -q "smooth-scrolling" $chflags || echo '--disable-smooth-scrolling' >> $chflags

Full list of currently supported flags for the Chrome browser can be find here.

24 ) How to block or unblock certain keyboard shortcuts in kiosk?

Keyboard shortcuts are blocked on the window manager level and it depends on the system used (Kiosk, Cloud, Thin Client, Server) and your kiosk configuration which ones are blocked by default.

Please login to kiosk over SSH and run following command to find all shortcuts which are blocked in your system:

grep -A1 'Disable following keybindings' /etc/xdg/openbox/rc.xml

In order to block F11 key and Ctrl+D shortcut please use following 'run_command=' parameter:

run_command=sed -e 's/ Menu / Menu F11 C-d /' -i /etc/xdg/openbox/rc.xml; openbox --reconfigure

In order to unblock Ctrl+B and Ctrl+D shortcuts please use following 'run_command=' parameter:

run_command=sed -e 's/C-b //' -e 's/C-d //' -i /etc/xdg/openbox/rc.xml; openbox --reconfigure

25 ) Where can I get additional help?

Please have a look on our paid support page.