Basic Customization

[davidb]

This process uses certain programs built into Porteus Linux, and while they can be added to any distro, it was easy enough to set up and install Porteus to a Virtual Machine using Virtual Box on a Windows machine.
Once you are up and running your VM, log in as root or use "su -" to become root
Enable SSH on the VM with the following commands:

Code: Select all

# chmod +x /etc/rc.d/rc.sshd
# /etc/rc.d/rc.sshd start 

Once this is done, you can connect via SSH instead of working within the VM.
Download the ISO and xzm modules for the version you are working with from http://porteus-kiosk.org/public/ (this example uses 3.7 folder)

Code: Select all

# wget -r --no-parent --reject "index.html*" http://porteus-kiosk.org/public/3.7/

After the download is complete, you will have a file structure mimicking the web site, enter the new directory:

Code: Select all

# cd porteus-kiosk.org

Create a working directory for the modified build

Code: Select all

# mkdir -p private/3.7/

Create a space to unpack the xzm modules

Code: Select all

# mkdir -p xzm-unpacked/3.7/

Mount the existing ISO and copy the contents to the private workspace

Code: Select all

# mount -o loop public/3.7/Porteus-Kiosk-3.7.0-i586.iso /mnt/cdrom
# mkdir private/3.7/kiosk_ISO
# cp -a /mnt/cdrom/* private/3.7/kiosk_ISO/
# umount /mnt/cdrom

While the extra modules are found in the "public/3.7/" directory we downloaded, the core OS files and settings are in the ISO we unpacked. We will make a copy of them before modifying them as well.

Code: Select all

# cp private/3.7/kiosk_ISO/xzm/* public/3.7/

Move into your workspace at this point, and we'll unpack the xzm files we want to modify

Code: Select all

# mkdir xzm-unpacked/3.7/003-settings
# xzm2dir public/3.7/003-settings.xzm xzm-unpacked/3.7/003-settings

Repeat this mkdir/xzm2dir process for any other modules that need modification
********************************
In this example we will change the default chrome search provider, remove the "sleep" button from the ctl-alt-del menu, and change the installer/default background image.
This is done in the unpacked xzm modules.
********************************
********************************
It was pointed out that the purpose of the xzm modules and file system model is to be flexible, and modifying the core modules is usually unnecessary.
I still would recommend unpacking them to better understand how Porteus-Kiosk works, as i would not have found the files i wanted to modify without doing so.
With that in mind, i will leave this section here so people know how to do it, but i have added a section on creating your own module for these changes.
********************************
Use your prefered text editor to modify these files, I will use vi for some reason (thanks dad)
To change the default chrome search provider to Google:

Code: Select all

# vi xzm-unpacked/3.7/003-settings/etc/opt/chrome/policies/managed/chrome.json

Find the line that reads "DefaultSearchProviderName": "DDG",
and change it to "DefaultSearchProviderName": "Google",
Find the line that reads "DefaultSearchProviderSearchURL": "https://duckduckgo.com/?t=porteus&q={searchTerms}",
and change it to "DefaultSearchProviderSearchURL": "https://www.google.com/search?q={searchTerms}",
To remove the "Sleep" button from the ctl-alt-del menu:

Code: Select all

# vi xzm-unpacked/3.7/003-settings/opt/porteus-scripts/exit-kiosk

remove the xml <button> element that contains the sleep function (6 lines)
find the <window> element opening line, at the end change the 'height-request="250"'
to 'height-request="195"' so there is not extra space at the bottom of the ctl-alt-del menu.
(reduce by approx 55px for each button removed)
After you are done making changes, you need to create a new xzm module for the custom ISO. This will overwrite the existing xzm file
# dir2xzm xzm-unpacked/3.7/003-settings/ private/3.7/kiosk_ISO/xzm/003-settings.xzm
********************************[/i]
********************************
Instead of modifying the default modules, lets create our own xzm.

Code: Select all

# mkdir xzm-unpacked/3.7/005-custom

The folder structure in our new module must match that of the root file system, so we must create it

Code: Select all

# mkdir -p xzm-unpacked/3.7/005-custom/opt/porteus-scripts/
# mkdir -p xzm-unpacked/3.7/005-custom/etc/opt/chrome/policies/managed/

Copy the files we want to modify to the new module

Code: Select all

# cp xzm-unpacked/3.7/003-settings/opt/porteus-scripts/exit-kiosk xzm-unpacked/3.7/005-custom/opt/porteus-scripts/
# cp xzm-unpacked/3.7/003-settings/etc/opt/chrome/policies/managed/chrome.json xzm-unpacked/3.7/005-custom/etc/opt/chrome/policies/managed/

Use your prefered text editor to modify these files, I will use vi for some reason (thanks dad)
To change the default chrome search provider to Google:

Code: Select all

# vi xzm-unpacked/3.7/005-custom/etc/opt/chrome/policies/managed/chrome.json

Find the line that reads "DefaultSearchProviderName": "DDG",
and change it to "DefaultSearchProviderName": "Google",
Find the line that reads "DefaultSearchProviderSearchURL": "https://duckduckgo.com/?t=porteus&q={searchTerms}",
and change it to "DefaultSearchProviderSearchURL": "https://www.google.com/search?q={searchTerms}",
To remove the "Sleep" button from the ctl-alt-del menu:

Code: Select all

# vi xzm-unpacked/3.7/005-custom/opt/porteus-scripts/exit-kiosk

remove the xml <button> element that contains the sleep function (6 lines)
find the <window> element opening line, at the end change the 'height-request="250"'
to 'height-request="195"' so there is not extra space at the bottom of the ctl-alt-del menu.
(reduce by 55px for each button removed)
Create the module and add it to the kiosk_ISO folder for inclusion with new ISO

Code: Select all

# dir2xzm xzm-unpacked/3.7/005-custom/ private/3.7/kiosk_ISO/xzm/005-custom.xzm

********************************
The default background image for porteus kiosk is found at private/3.7/kiosk_ISO/docs/default.jpg
Replacing this file with your own image will change it across the board, unless the "wallpaper=" parameter is set in a config file. The original image is 1600x1000 pixels. (not in a xzm module)
********************************
Add the extra modules to the ISO so they don't have to be downloaded from the internet for this to have any benefit, the initial configuration of the kiosk must have these parameters:

Code: Select all

additional_components=08-ssh.xzm 09-x11vnc.xzm 10-printing.xzm uefi.zip

Code: Select all

# cp public/3.7/08-ssh.xzm private/3.7/kiosk_ISO/xzm/
# cp public/3.7/09-x11vnc.xzm private/3.7/kiosk_ISO/xzm/
# cp public/3.7/10-printing.xzm private/3.7/kiosk_ISO/xzm/
# cp public/3.7/uefi.zip private/3.7/kiosk_ISO/xzm/
# cp public/3.7/002-chrome.xzm private/3.7/kiosk_ISO/xzm/

Once all desired modules are in the kiosk_ISO file, move to that directory and run the script to build the custom ISO (must be in correct directory)

Code: Select all

# cd private/3.7/kiosk_ISO/
# ./make_iso.sh

The resulting ISO will be named "Porteus-Kiosk.iso" in the parent directory, rename it to be able to identify it (i.e. base version, date, time, build number etc) and so it is not overwritten by future runs of the make_iso script.

Code: Select all

# cd ..
# mv Porteus-Kiosk.iso PK-3.7.0-ACME-17Jun2016-beta3.iso

If creating a CD Only ISO, you can use this file, otherwise...
To create an ISO for use with a USB drive:
Install the syslinux package from the slackware repository (change /mnt/sda1 to your media)

Code: Select all

# cd ~
# mkdir slackware-packages
# cd slackware-packages
# wget https://slackbuilds.org/mirror/slackware/slackware-14.1/slackware/a/syslinux-4.06-i486-1.txz
# txz2xzm syslinux-4.06-i486-1.txz
# cp syslinux-4.06-i486-1.xzm /mnt/sda1/porteus/optional/
# activate /mnt/sda1/porteus/optional/syslinux-4.06-i486-1.xzm
# cp /mnt/sda1/porteus/optional/syslinux-4.06-i486-1.xzm /mnt/sda1/porteus/modules/syslinux-4.06-i486-1.xzm

The last command will make it load on boot without having to activate it again
Run the next commands to make your ISO bootable on a USB drive

Code: Select all

# cd ~/porteus-kiosk.org/private/3.7/
# isohybrid PK-3.7.0-ACME-17Jun2016-beta3.iso

Use WinSCP to transfer the new ISO to your local computer and burn the disk.
The USB must be written with a program like Win32DiskImager (see kiosk download page for link)

Keep in mind that this custom ISO is unlikely to be compatible with updates in the future or your changes could be overwritten, so record your customizations for future use!*
*Keeping your custom settings and configuration in a separate xzm module is much easier to manage in the event of an update, since they are kept separate from the core of Porteus Kiosk.
Its probably not recommended to add both chrome and firefox to the default ISO (or either according to the developers haha), just the one you plan to use. if remote config is enabled, it will download from the porteus kiosk site if you change it in the future.

Feedback is always welcome

RESOURCES:
http://porteus-kiosk.org/kiosk-customization.html
http://porteus-kiosk.org/modules.html
http://porteus-kiosk.org/download.html

[fanthom]

Hello davidb,

Great tutorial

Just to add few things:
1) instead of unsquashing base modules you should create your own xzm and take advantage of aufs layered filesystem structure: http://porteus-kiosk.org/file-structure.html. Its easier to maintain your custom changes in case of doing a kiosk upgrade.
2) when modifying browser settings (like search engine for Chrome) sometimes may be easier to use designated kiosk API:
http://porteus-kiosk.org/parameters.htm ... references
3) 'run_command=' parameter is also handy. You may use it to inject Firefox addons, certificates or any other file/utility to the kiosk filesystem. If you know shell scripting then you can do almost everything with it - no need to modify the ISO.

Thank you.

[davidb]

Thank you for the points you added, i feel like went about it the hard way haha. a couple more questions if you don't mind...
1)re: file structure, i tried creating a module that made the changes to the files modified above (exit-kiosk & chrome.json) and named it 005-custom.xzm but the changes did not show up in the running system. I thought maybe a module that loads after another one could update files after they were loaded the first time, but it appears not to work this way? Would i want to name it 002-custom so it loads before the 003-settings module? I would much rather do it this way for sure, once i get that working to my satisfaction i will update the post to reflect it. However I must say its been useful rooting around in the base modules to learn the system.
2)re: browser settings, you are correct that it would be easier, but when specifying a browser_preferences file it causes problems when you restart a session (tries to check if its default browser, homepages no longer load)
3)i'll need to touch up on my scripting skills, this sounds very useful.

edit: i made a stupid naming mistake it does in fact work, just like you said it did haha.

[ch4lk]

...If creating a CD Only ISO, you can use this file, otherwise...
To create an ISO for use with a USB drive:...l

Apologies for resurrecting a very old thread

As an utter slackware newbie, I was about creating a USB bootable version.
I'm trying to make a customised porteus-kiosk with chrome browser and printing module incorporated. (I'm learning a lot about failing and trying again....)

I completely misunderstood that for a bootable USB to work, it has to be post processed by isohybrid (reading this: http://www.syslinux.org/wiki/index.php? ... _DISK_MODE. I foolishly thought that to accomplish USB bootability I had to run isohybrid instead of the 'make_iso.sh' script. But no, first the script, then isohybrid.
David, if I am wrong, could you please clarify your instructions, and, if I am right, could you modify your instructions? And I'll do so more investigating why my usb won't boot in the meantime.

[ch4lk]

is it inappropriate to answer your own question?
I've worked out my usb bootable isohybrid problem. Because I was using Debian 'Jessie', I just needed to install the 'syslinux-utils' package on my distro and the usb is now bootable. This was discovered thanks to this post from Tony Mancill here https://www.turnkeylinux.org/comment/22 ... ment-22029